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

<?php
$path = tempnam(sys_get_temp_dir(), 'dba-');
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('База не открыта'); }
dba_insert('user:42:language', 'ru', $db);
echo dba_fetch('user:42:language', $db), "\n";
dba_close($db);
unlink($path);

ru

tempnam создаёт только наш новый временный файл; n инициализирует его. Ключ user:42:language — наша договорённость об имени, значение ru — строка. dba_open возвращает соединение, insert сохраняет, fetch возвращает значение, close завершает. flatfile выбран для учебного опыта и совместимости; это не рекомендация для большой рабочей базы.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('delivery:pickup', 'Самовывоз', $db);
dba_close($db);
$db = dba_open($path, 'r', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось прочитать базу'); }
echo dba_fetch('delivery:pickup', $db), "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

Самовывоз

После закрытия данные остались в файле. r не позволяет менять их через это соединение; w откроет существующий файл для записи, c также разрешит создать отсутствующий. n обнулит существующий файл, поэтому его нельзя подставлять как обычное «открыть».

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
var_dump(dba_insert('currency', 'RUB', $db));
var_dump(dba_insert('currency', 'USD', $db));
echo dba_fetch('currency', $db), "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

bool(true)
bool(false)
RUB

Для обычного unique-key handler insert отказал второй раз и сохранил RUB. Если по требованию нужна замена, используйте replace. Поведение duplicate-capable inifile/cdb описано отдельно: не стройте универсальное ограничение уникальности поверх любого handler.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
$profile = ['language' => 'ru', 'theme' => 'dark'];
$value = json_encode($profile, JSON_THROW_ON_ERROR);
if (!dba_insert('user:42', $value, $db)) { throw new RuntimeException('Профиль не записан'); }
$raw = dba_fetch('user:42', $db);
if ($raw === false) { throw new RuntimeException('Профиль не найден'); }
$loaded = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
echo $loaded['theme'], "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

dark

DBA хранит строку JSON как неделимое значение, не отдельные поля. Чтобы искать всех пользователей с theme=dark, придётся обходить и декодировать записи; для сложных выборок удобнее SQLite. JSON проверяется при кодировании/чтении, а структуру из внешнего источника проверяют дополнительно.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('theme', 'light', $db);
var_dump(dba_replace('theme', 'dark', $db));
echo dba_fetch('theme', $db), "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

bool(true)
dark

replace выбирает новую строку целиком. У него нет SQL-условия WHERE old_value=... и универсального compare-and-swap; согласованность нескольких шагов требует правил блокировки.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_replace('sync:catalog:cursor', 'page-1', $db);
dba_replace('sync:catalog:cursor', 'page-2', $db);
echo dba_fetch('sync:catalog:cursor', $db), "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

page-2

replace работает и для отсутствующего ключа. Но курсор нельзя продвигать до успешного сохранения данных страницы: DBA не предоставляет общую транзакцию между этим файлом и сторонней SQL-базой.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('count', '0', $db);
dba_insert('note', '', $db);
var_dump(dba_fetch('count', $db));
var_dump(dba_fetch('note', $db));
var_dump(dba_fetch('missing', $db));
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

string(1) "0"
string(0) ""
bool(false)

Возврат — строка либо false. if (!$value) смешает все три случая; === false обнаруживает именно отсутствие/отказ, а "0" можно затем отдельно проверить и преобразовать в число.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
$language = dba_fetch('user:77:language', $db);
if ($language === false) { $language = 'ru'; }
echo $language, "\n";
dba_insert('user:77:language', 'en', $db);
echo dba_fetch('user:77:language', $db), "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

ru
en

Default выбран приложением, не DBA. Проверка существования перед каждым fetch обычно делает лишнюю операцию; часто проще один fetch и строгая проверка.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('banner', '', $db);
var_dump(dba_exists('banner', $db));
var_dump(dba_exists('missing', $db));
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

bool(true)
bool(false)

Ключ banner существует, хотя его значение пустое. exists отвечает о наличии, а не истинности сохранённой строки.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('language', 'en', $db);
if (!dba_exists('language', $db)) { dba_insert('language', 'ru', $db); }
echo dba_fetch('language', $db), "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

en

Здесь эксклюзивное write-открытие удерживается на всю пару exists+insert. Если отключить блокировки или разнести шаги между открытиями, другой writer может вмешаться; для уникального handler результат insert сам по себе важнее предварительной проверки.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('cache:weather', 'old response', $db);
var_dump(dba_delete('cache:weather', $db));
var_dump(dba_exists('cache:weather', $db));
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

bool(true)
bool(false)

Удалён ключ вместе со значением. Освобождение места внутри файла зависит от формата; размер файла не обязан немедленно уменьшиться.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
$key = 'draft:old';
if (dba_exists($key, $db)) {
    if (!dba_delete($key, $db)) { throw new RuntimeException('Удаление не выполнено'); }
}
echo "Старого черновика нет\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

Старого черновика нет

Приложение считает отсутствие нормальным конечным состоянием. Не следует превращать любое false удаления в успешную очистку без понимания причины; путь проверки находится под write-lock.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('theme', 'dark', $db);
dba_insert('language', 'ru', $db);
$settings = [];
for ($key = dba_firstkey($db); $key !== false; $key = dba_nextkey($db)) { $settings[$key] = dba_fetch($key, $db); }
ksort($settings);
foreach ($settings as $key => $value) { echo $key, '=', $value, "\n"; }
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

language=ru
theme=dark

firstkey сбрасывает внутреннюю позицию, nextkey двигает её. Порядок обхода зависит от handler: для стабильного вывода явно сортируем маленький собранный массив. Большую базу целиком так собирать дорого.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('0', 'zero', $db);
$count = 0;
for ($key = dba_firstkey($db); $key !== false; $key = dba_nextkey($db)) { ++$count; }
echo $count, "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

1

Условие while($key) потеряло бы строковый ключ "0". Точный признак окончания — false. Для пустой базы firstkey сразу вернёт false.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('theme', 'dark', $db);
dba_insert('language', 'ru', $db);
$settings = [];
for ($key = dba_firstkey($db); $key !== false; $key = dba_nextkey($db)) { $settings[$key] = dba_fetch($key, $db); }
ksort($settings);
foreach ($settings as $key => $value) { echo $key, '=', $value, "\n"; }
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

language=ru
theme=dark

firstkey сбрасывает внутреннюю позицию, nextkey двигает её. Порядок обхода зависит от handler: для стабильного вывода явно сортируем маленький собранный массив. Большую базу целиком так собирать дорого.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('0', 'zero', $db);
$count = 0;
for ($key = dba_firstkey($db); $key !== false; $key = dba_nextkey($db)) { ++$count; }
echo $count, "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

1

Условие while($key) потеряло бы строковый ключ "0". Точный признак окончания — false. Для пустой базы firstkey сразу вернёт false.

<?php
$parts = dba_key_split('[mail]sender');
echo $parts[0], ':', $parts[1], "\n";
$plain = dba_key_split('language');
echo $plain[0] === '' ? "Без секции:" : $plain[0];
echo $plain[1], "\n";

mail:sender
Без секции:language

Это специальный синтаксис ключей inifile, не разбиение любого ключа по двоеточию. Строка user:42 остаётся целым именем без секции.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'inifile');
if ($db === false) { throw new RuntimeException('INI не открыт'); }
dba_insert(['delivery', 'city'], 'Tula', $db);
for ($key = dba_firstkey($db); $key !== false; $key = dba_nextkey($db)) {
    [$group, $name] = dba_key_split($key);
    if ($name === '') { echo 'Секция:', $group, "\n"; continue; }
    echo $group, '/', $name, '=', dba_fetch([$group, $name], $db), "\n";
}
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

Секция:delivery
delivery/city=Tula

Обход inifile возвращает и отдельную секцию с пустым именем. Её показываем отдельно. Сначала проверяем конец обхода, затем разбираем строку. dba_key_split(false/null) исторически возвращает false, но с PHP8.4 оба варианта deprecated. Учебный INI — наш файл, не настоящий php.ini сервера.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('status', 'ready', $db);
dba_close($db);
$db = dba_open($path, 'r', 'flatfile');
echo dba_fetch('status', $db), "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

ready

Обычный write-handle удерживает lock до закрытия. Отдельный reader открывается после close, поэтому не ждёт нашу собственную блокировку.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_close($db);
try { dba_fetch('status', $db); }
catch (Error $error) { echo "Соединение уже закрыто\n"; }
unlink($path);
rmdir($directory);

Соединение уже закрыто

Переменная всё ещё содержит PHP-объект, но внутренний handle уже недействителен. is_object не проверяет открытость; управление сроком жизни должно быть явным.

<?php
$handlers = dba_handlers();
echo in_array('flatfile', $handlers, true) ? "Учебный flatfile доступен\n" : "Нужен другой handler\n";
echo in_array('lmdb', $handlers, true) ? "LMDB доступен\n" : "LMDB не включён\n";

Учебный flatfile доступен
LMDB доступен

Вывод соответствует проверочной bundled-сборке. Список на Linux-сервере или другом php.ini может отличаться; наличие расширения DBA не означает наличия всех handlers.

<?php
$details = dba_handlers(true);
foreach (['cdb', 'qdbm', 'lmdb'] as $name) {
    echo $name, ':', isset($details[$name]) && $details[$name] !== '' ? 'описание есть' : 'не установлен', "\n";
}

cdb:описание есть
qdbm:описание есть
lmdb:описание есть

true меняет форму ответа: ключи — имена handlers, значения — их версии/описания. Эти строки годятся для диагностики, но не являются стабильным машинным форматом.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
$opened = dba_list();
echo in_array(realpath($path), array_map('realpath', $opened), true) ? "Учебный файл открыт\n" : "Файл не найден\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

Учебный файл открыт

realpath нормализует путь и разделители Windows перед сравнением. dba_list показывает открытые handles текущего контекста, а не все .db-файлы диска и не подключения других workers. Не выводите полные серверные пути посетителю.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
$before = count(dba_list());
dba_close($db);
echo $before - count(dba_list()), "\n";
unlink($path);
rmdir($directory);

1

После close один обычный handle исчез. Числовые ключи массива — технические идентификаторы, не стабильные номера файлов и не интерфейс для восстановления соединения.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_insert('cache:1', 'old', $db);
dba_delete('cache:1', $db);
var_dump(dba_optimize($db));
var_dump(dba_exists('cache:1', $db));
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

bool(true)
bool(false)

В tagged flatfile optimize — no-op с true. Поэтому true нельзя переводить как «файл уменьшился» или «доступ ускорился». Это успешное действие в контракте handler, которое здесь ничего не перестраивает.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'qdbm');
if ($db === false) { throw new RuntimeException('QDBM недоступен'); }
dba_insert('keep', 'value', $db);
dba_insert('remove', 'old', $db);
dba_delete('remove', $db);
var_dump(dba_optimize($db));
echo dba_fetch('keep', $db), "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

bool(true)
value

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

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Не удалось открыть учебную базу'); }
dba_replace('build', 'ready', $db);
var_dump(dba_sync($db));
echo dba_fetch('build', $db), "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

bool(true)
ready

В flatfile sync также no-op; true не доказывает fsync и устойчивость к отключению питания. Совпадение fetch доказывает только видимость значения в этой проверке.

<?php
$directory = sys_get_temp_dir() . '/dba-' . bin2hex(random_bytes(8));
mkdir($directory, 0700);
$path = $directory . '/demo.db';
$db = dba_open($path, 'n', 'qdbm');
if ($db === false) { throw new RuntimeException('QDBM недоступен'); }
dba_insert('snapshot', 'v2', $db);
if (!dba_sync($db)) { throw new RuntimeException('Синхронизация не выполнена'); }
dba_close($db);
$db = dba_open($path, 'r', 'qdbm');
echo dba_fetch('snapshot', $db), "\n";
dba_close($db);
foreach (glob($directory . '/*') as $file) { unlink($file); }
rmdir($directory);

v2

Драйвер QDBM использует собственную процедуру sync; после закрытия читаем новым handle. Это полезный функциональный опыт, не испытание сбоя питания и не обещание атомарности нескольких ключей.

<?php
$path = tempnam(__DIR__, 'dba-cache-');
$db = dba_popen($path, 'n', 'flatfile');
if ($db === false) { throw new RuntimeException('Persistent база не открыта'); }
dba_insert('catalog:version', 'v1', $db);
echo dba_fetch('catalog:version', $db), "\n";
dba_close($db);

v1

Запускайте сохранённый пример только в отдельном учебном каталоге. Созданный уникальный dba-cache-* удаляют после завершения PHP-процесса, когда закрыт persistent backend; проверочная среда делает это автоматически. В коротком CLI нет следующего HTTP-запроса для выигрыша от persistent-пула.

<?php
$path = tempnam(__DIR__, 'dba-cache-');
$first = dba_popen($path, 'c', 'flatfile');
if ($first === false) { throw new RuntimeException('База не открыта'); }
dba_replace('language', 'ru', $first);
dba_close($first);
$second = dba_popen($path, 'c', 'flatfile');
if ($second === false) { throw new RuntimeException('Повторное открытие не удалось'); }
echo dba_fetch('language', $second), "\n";
dba_close($second);

ru

Совпадение path/mode/handler позволяет этой реализации переиспользовать backend процесса. Это не общий пул всех workers, не общая PHP-переменная и не обещание, что close освободил persistent lock. Учебный файл удаляется внешней средой после процесса; рабочий файл хранится осознанно.