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

SQLSRV: точная первая версия не указана в PHP Manual; проверенный профиль указан в главе · sqlsrv

sqlsrv_query(resource $conn, string $sql, array $params = [], array $options = []): resource|false

Один раз выполнить параметризованный запрос и получить ресурс результата.

Ресурс означает, что команда подготовлена и выполнена; строки ещё читаются отдельно. false означает отказ, после которого сразу сохраните sqlsrv_errors().

Направление по умолчанию — SQLSRV_PARAM_IN. PHP-тип задаётся SQLSRV_PHPTYPE_*, серверный — SQLSRV_SQLTYPE_*. Не путайте строковое число с выбранным SQL DECIMAL. Параметры OUT/INOUT читаются после завершения всех возвращённых результатов; для строк задаётся достаточная длина.

Показать один счёт

SELECT выбирает поля и нужный ID на сервере. Параметр не подставляется вручную внутрь SQL.

$stmt = sqlsrv_query($db, "SELECT invoice_no, qty FROM $q WHERE id = ?", [1]);
if ($stmt === false) { $errors = sqlsrv_errors(); }

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

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

В одной команде передаются Unicode-текст и строка DECIMAL. query подходит для однократной записи, а возвращаемый ресурс не является вставленным объектом.

$params = [
    [$title, SQLSRV_PARAM_IN, SQLSRV_PHPTYPE_STRING("UTF-8"), SQLSRV_SQLTYPE_NVARCHAR("80")],
    [$price, SQLSRV_PARAM_IN, SQLSRV_PHPTYPE_STRING("UTF-8"), SQLSRV_SQLTYPE_DECIMAL(19, 4)]
];
$stmt = sqlsrv_query($db, "INSERT INTO $q (id, title, price) VALUES (1, ?, ?)", $params);

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

? заменяет значение, не имя таблицы, поле или ASC/DESC. Идентификатор $q в самостоятельном примере создан и проверен helper; значение формы сюда не попадает. Для повторного выполнения одной структуры используйте prepare/execute. Не передавайте false дальше в fetch или rows_affected.

Связанные действия: sqlsrv_query, sqlsrv_prepare, sqlsrv_execute, sqlsrv_fetch_array, диагностика SQLSRV.

• PHP Manual — sqlsrv_query
• Microsoft — sqlsrv_query

SQLSRV: точная первая версия не указана в PHP Manual; проверенный профиль указан в главе · sqlsrv

sqlsrv_prepare(resource $conn, string $sql, array $params = [], array $options = []): resource|false

Связать SQL с параметрами для повторных выполнений.

Ресурс подготовленной команды или false. Подготовка ещё не выполняет предметную запись: для неё вызывается execute.

Направление по умолчанию — SQLSRV_PARAM_IN. PHP-тип задаётся SQLSRV_PHPTYPE_*, серверный — SQLSRV_SQLTYPE_*. Не путайте строковое число с выбранным SQL DECIMAL. Параметры OUT/INOUT читаются после завершения всех возвращённых результатов; для строк задаётся достаточная длина.

Прочитать два разных счёта

&$id связывает statement с самой переменной; изменение её значения будет видно следующему execute.

$id = 1;
$stmt = sqlsrv_prepare($db, "SELECT invoice_no, qty FROM $q WHERE id = ?", [&$id]);
// Проверить false, выполнить, прочитать строки.
$id = 2; // Следующий execute использует 2.

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

Повторно менять количество

Одна структура UPDATE и две связанные переменные удобны для последовательных позиций документа. Завершайте результат каждого выполнения.

$qty = 1; $id = 1;
$stmt = sqlsrv_prepare($db, "UPDATE $q SET qty = ? WHERE id = ?", [&$qty, &$id]);
// Изменять qty/id и вызывать execute для каждой операции.

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

Для изменяемого параметра передавайте ссылку, а не копию значения. Не переиспользуйте эту же переменную как случайную переменную foreach по ссылке: изменится связанное хранилище. OUT/INOUT тоже требуют связанной переменной и завершения всех результатов до чтения выхода; потоки, null и DateTime нельзя использовать как выходные значения.

Связанные действия: sqlsrv_query, sqlsrv_prepare, sqlsrv_execute, sqlsrv_fetch_array, диагностика SQLSRV.

• PHP Manual — sqlsrv_prepare
• Microsoft — sqlsrv_prepare

SQLSRV: точная первая версия не указана в PHP Manual; проверенный профиль указан в главе · sqlsrv

sqlsrv_execute(resource $stmt): bool

Выполнить подготовленную команду с текущими связанными значениями.

true — исполнение принято, false — ошибка. true не равно строкам SELECT и не равно количеству изменённых строк.

Получить текущий счёт

Сначала execute, затем fetch_array до null. Между повторениями меняется $id, а ресурс остаётся тем же.

$id = 1;
if (sqlsrv_execute($stmt) === false) { $errors = sqlsrv_errors(); }
// Прочитать результат полностью.
$id = 2;
// Выполнить и прочитать второй результат.

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

Проверить отказ изменения

После execute(false) сохраните ошибки; нельзя выводить пользователю «сохранено» по одному наличию подготовленного ресурса.

$ok = sqlsrv_execute($update);
if ($ok === false) {
    $errors = sqlsrv_errors();
} else {
    $affected = sqlsrv_rows_affected($update);
}

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

Не выполняйте ресурс после free_stmt. Подготовленные параметры живут вместе со statement и связанными переменными. Перечитывание или освобождение результата — отдельный этап; успешный execute не гарантирует прохождения последующего fetch.

Связанные действия: sqlsrv_query, sqlsrv_prepare, sqlsrv_execute, sqlsrv_fetch_array, диагностика SQLSRV.

• PHP Manual — sqlsrv_execute
• Microsoft — sqlsrv_execute

SQLSRV: точная первая версия не указана в PHP Manual; проверенный профиль указан в главе · sqlsrv

sqlsrv_field_metadata(resource $stmt): array|false

Узнать имена и SQL-типы полей до преобразования результата.

Массив описаний полей или false. Name — имя/псевдоним, Type — числовой SQL-тип, Size — длина текста либо байтов бинарного поля; Precision/Scale — точность и дробная часть, Nullable — YES/NO/UNKNOWN. Неприменимые сведения могут быть null.

Проверить цену перед выгрузкой

Описание SQL DECIMAL и PHP-тип его прочитанного значения — разные сведения. Сохраняйте и точность, и строковое значение.

$fields = sqlsrv_field_metadata($stmt);
if ($fields === false) { $errors = sqlsrv_errors(); }
// Найти поле price по Name и проверить Precision/Scale.

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

Различить дату и момент со смещением

Метаданные объясняют, почему дата без часового пояса и datetimeoffset требуют разных правил вывода.

$fields = sqlsrv_field_metadata($stmt);
foreach ($fields as $field) {
    echo $field["Name"], ": SQL type ", $field["Type"], "\n";
}

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

Name относится к выражению результата, включая AS; одинаковые имена после JOIN не создают автоматически уникальные ключи. Nullable:0 — NULL запрещён,1 — разрешён,2 — неизвестно. Nullable UNKNOWN не означает «запрещён NULL». При DataClassification=true возможны дополнительные сведения о классификации и ранге; они не заменяют проверки прав приложения.

Связанные действия: sqlsrv_query, sqlsrv_prepare, sqlsrv_execute, sqlsrv_fetch_array, диагностика SQLSRV.

• PHP Manual — sqlsrv_field_metadata
• Microsoft — sqlsrv_field_metadata

SQLSRV: точная первая версия не указана в PHP Manual; проверенный профиль указан в главе · sqlsrv

sqlsrv_fetch_array(resource $stmt, int $fetchType = SQLSRV_FETCH_BOTH, int $row = SQLSRV_SCROLL_NEXT, int $offset = 0): array|null|false

Прочитать одну строку, отдельно отличая конец результата и ошибку.

array — строка, null — строк больше нет, false — ошибка чтения. Эти три состояния требуют строгого сравнения.

Показать строки без потери ошибки

Цикл с явными ветвями не принимает ошибку за пустой каталог. SQL уже ограничивает нужные строки и порядок.

while (true) {
    $row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
    if ($row === null) { break; }
    if ($row === false) { $errors = sqlsrv_errors(); break; }
    // Вывести выбранные поля row с HTML-экранированием.
}

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

Вывести календарную дату

DateTime форматируется методом format; (string) и strtotime не превращают автоматически объект в нужную подпись.

$row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
if (is_array($row) && $row["delivery_date"] instanceof DateTimeInterface) {
    echo $row["delivery_date"]->format("d.m.Y");
}

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

Задавайте уникальные AS для одноимённых полей JOIN; безымянное выражение получает пустой ключ. BOTH содержит одно значение под двумя ключами — count(row) не равно числу столбцов. Обычное чтение идёт вперёд; скроллинг требует соответствующей Scrollable-настройки. PHP.net в описании row ошибочно называет RELATIVE значением по умолчанию: рабочий последовательный вызов читает NEXT.

Связанные действия: sqlsrv_query, sqlsrv_prepare, sqlsrv_execute, sqlsrv_fetch_array, диагностика SQLSRV.

• PHP Manual — sqlsrv_fetch_array
• Microsoft — sqlsrv_fetch_array

SQLSRV: точная первая версия не указана в PHP Manual; проверенный профиль указан в главе · sqlsrv

sqlsrv_free_stmt(resource $stmt): bool

Освободить ресурс statement после чтения или отказа.

true при освобождении, false при ошибке операции; неверный PHP-тип или уже закрытый ресурс может вызвать TypeError. После освобождения caller-переменная в проверенном профиле имеет resource(closed), а не null; присвойте null явно. Освобождённый statement повторно выполнять нельзя.

Закрыть результат даже при исключении

Ресурс освобождается в finally, а сохранённый PHP-массив остаётся доступен.

try {
    $row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
    // Обработать row/null/false.
} finally {
    if (is_resource($stmt)) { sqlsrv_free_stmt($stmt); }
    $stmt = null;
}

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

Закончить серию повторных выполнений

Освобождайте подготовленный statement после последнего execute, а не перед следующим использованием.

// Все prepare/execute/fetch этой серии завершены.
$released = sqlsrv_free_stmt($prepared);
$prepared = null;
// Соединение db можно использовать для новой команды.

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

cancel сохраняет возможность повторного execute подготовленной команды; free_stmt освобождает её ресурс. Не используйте освобождение как способ отката записи. Старое примечание PHP.net о прекращении незавершённой команды не является переносимым бизнес-контрактом: в исходниках драйвера 5.13.3 деструктор дочитывает ожидающие результаты перед освобождением. Управление транзакцией и явный rollback разбираются отдельно.

Связанные действия: sqlsrv_query, sqlsrv_prepare, sqlsrv_execute, sqlsrv_fetch_array, диагностика SQLSRV.

• PHP Manual — sqlsrv_free_stmt
• Microsoft — sqlsrv_free_stmt

SQLSRV: точная первая версия не указана в PHP Manual; проверенный профиль указан в главе · sqlsrv

sqlsrv_rows_affected(resource $stmt): int|false

Различить изменённые строки, отсутствие совпадений и неизвестное количество.

Неотрицательное число — количество затронутых строк;0 — ни одной;−1 — количество недоступно;false — ошибка. Для количества строк SELECT служат другие операции.

Подтвердить изменение заказа

Сначала проверяется успешность query/execute, затем счётчик. Строгое ===false не путает 0 с ошибкой.

$count = sqlsrv_rows_affected($stmt);
if ($count === false) { $errors = sqlsrv_errors(); }
elseif ($count === -1) { /* Число не сообщено. */ }
elseif ($count === 0) { /* Нет совпавшей строки. */ }
else { /* Получено конкретное количество. */ }

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

Проверить команду с NOCOUNT

Если сервер не отправляет счётчик, результат операции подтверждается данными или явной квитанцией SQL, а не предположением «−1 значит провал».

$stmt = sqlsrv_query($db, "UPDATE $q SET qty = ? WHERE id = ?", [9, 1]);
if ($stmt !== false) {
    $count = sqlsrv_rows_affected($stmt);
    // При NOCOUNT ON ожидается отсутствие сообщения о числе.
}

Это фрагмент после подготовки соединения и таблицы; полная запускаемая программа: перейти к сценарию и его результату.

Не передавайте false вместо statement и не подавляйте ошибки символом@. Значение−1 не является доказательством отсутствия записи. SELECT COUNT(*) считает строки по фильтру на сервере; rows_affected не заменяет этот запрос. Для конкурентного изменения нужна отдельная бизнес-квитанция или транзакционный сценарий.

Связанные действия: sqlsrv_query, sqlsrv_prepare, sqlsrv_execute, sqlsrv_fetch_array, диагностика SQLSRV.

• PHP Manual — sqlsrv_rows_affected
• Microsoft — sqlsrv_rows_affected