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

Зачем нужен DBF и как выглядит его таблица

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

Аналогия — журнал с заранее размеченными графами. В отличие от листа Excel, каждая строка здесь имеет фиксированную ширину, а формат и байты колонок нужно согласовать. PHP-массив служит представлением прочитанной строки; он не является самим DBF-файлом. Понятия массива, пути к файлу и цикла используются с коротким объяснением по мере появления.

PHP manual рекомендует SQLite либо SQL-сервер для основной базы сайта; dBase полезен прежде всего для импорта/экспорта. Поддерживаются уровни DBF 3–5 и перечисленные возможности FoxPro. Индексы и memo не поддерживаются. Расширение вынесено в PECL с PHP 5.3.0; наличие PHP само по себе не означает наличие функций dbase.

Подготовить PHP и понять ресурс dbase

Проверьте расширение именно в том PHP, которым запускается example.php. Пакет этой главы выполнен в изолированном PHP 8.5.11 NTS x64 с официальным dbase 7.1.1; iconv нужен сценарию кодировки. На сервере PHP CLI и FPM/Apache могут читать разные php.ini. Установка расширения не требует создавать SQL-сервер.

Установка и первая проверка

Источник — PECL dbase и инструкция установки PECL. В Linux расширение собирают для установленного PHP: нужны его совместимые phpize/php-config и средства сборки; после установки включают extension=dbase. На Windows выбирайте официальную DLL под точную ветку PHP, x64/x86, TS/NTS и компилятор, затем подключайте её в ini или ключом -d extension=полный-путь. DLL для другой версии PHP нельзя исправить простым переименованием.

php --ini
php --ri dbase

Это команды терминала, не PHP-код. --ini показывает загруженную конфигурацию, --ri dbase — сведения о расширении. Если расширения нет, сначала устраните эту причину. Проверочный локальный запуск использует -n и явную DLL, поэтому не зависит от набора других расширений пользователя. Скачанные исходники, URL и контрольные суммы окружения сохранены в доказательствах пакета.

Ресурс и время его жизни

С dbase 7.0.0 create/open возвращают resource типа dbase. Это дескриптор открытого файла, не массив строк и не имя файла. После проверки !== false передавайте его в операции, затем закрывайте. Закрытый handle больше недействителен. finally закрывает файл даже при ошибке обработки; само исключение не скрывается.

Создать два столбца, добавить товары и прочитать сохранённый файл

Старая складская программа принимает остатки в DBF: у артикула A-100 есть 12 единиц, у B-200 — ноль. Создадим настоящий файл с двумя столбцами, закроем его и прочитаем заново. Получится переносимая таблица catalog.dbf. DBF состоит из заголовка со схемой и последовательно записанных строк одинаковой длины.

Что получится после повторного чтения

$schema = [['SKU', 'C', 6], ['QTY', 'N', 4, 0]];
$db = dbase_create(dbfPath('catalog.dbf'), $schema);
dbase_add_record($db, ['A-100', 12]);
dbase_close($db);

$schema — PHP-массив описаний столбцов. В первом описании SKU — имя, C — строка, 6 — её ширина в байтах; во втором N — число, 4 — общая ширина, 0 — число дробных знаков. Квадратные скобки создают массив; запятые разделяют элементы. dbase_create получает путь и схему, возвращает ресурс открытого файла либо false. dbase_add_record получает этот ресурс и позиционный массив: сначала SKU, затем QTY. В полной программе проверяются оба отказа. dbase_close закрывает ресурс; данные остаются. dbfPath из helper не разрешает перезаписать существующий учебный файл.

Открыть таблицу реального запуска · Скачать данные результата. HTML генерирует сама PHP-программа из прочитанных значений; для просмотра этой таблицы сервер не нужен.

Учебные DBF: catalog.dbf.

<?php
declare(strict_types=1);
require __DIR__ . '/dbf105-helper.php';

$schema = [['SKU', 'C', 6], ['QTY', 'N', 4, 0]];
$db = dbase_create(dbfPath('catalog.dbf'), $schema);
if ($db === false) { throw new RuntimeException('Cannot create catalog'); }
try {
    foreach ([['A-100', 12], ['B-200', 0]] as $values) {
        if (!dbase_add_record($db, $values)) { throw new RuntimeException('Cannot add product'); }
    }
} finally { dbase_close($db); }

$reader = dbfOpen('catalog.dbf');
try {
    $count = dbase_numrecords($reader); $rows = [];
    for ($number = 1; $number <= $count; $number++) {
        $row = dbase_get_record_with_names($reader, $number);
        if ($row === false) { throw new RuntimeException('Cannot read product'); }
        $rows[] = [$number, rtrim($row['SKU'], ' '), $row['QTY'], $row['deleted']];
    }
} finally { dbase_close($reader); }
dbfReport(['Record', 'SKU', 'QTY', 'deleted'], $rows, ['reopened' => true, 'records' => $count]);
echo "catalog.dbf: 2 records; A-100=12, B-200=0\n";

catalog.dbf: 2 records; A-100=12, B-200=0

Схема не содержит товаров: она задаёт места под их значения. Столбец SKU шириной 6 хранит A-100 и пробел заполнения. При чтении мы убираем только хвостовые пробелы через rtrim($value, " "). Ноль сохраняется числом 0. Колонку deleted мы не создавали: это служебный признак API чтения. Файл с расширением .dbf не обязательно совместим с любым читателем: семейство DBF имеет варианты.

Проверить схему файла до чтения строк

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

Что получится после повторного чтения

$header = dbase_get_header_info($db);
$columns = dbase_numfields($db);
$actualNames = array_column($header, 'name');

dbase_get_header_info возвращает список полей. name — имя, type — понятное название типа, length — байты, precision — дробные знаки, offset — смещение от начала записи, format — предложенный формат printf. Первая позиция списка имеет индекс 0. numfields возвращает количество колонок, numrecords — количество записей. array_column выбирает имена для простого сравнения. В рабочем импорте сравнивайте также типы, ширину и точность: одни имена не доказывают совместимость чисел.

Открыть таблицу реального запуска · Скачать данные результата. HTML генерирует сама PHP-программа из прочитанных значений; для просмотра этой таблицы сервер не нужен.

Учебные DBF: schema.dbf.

<?php
declare(strict_types=1);
require __DIR__ . '/dbf105-helper.php';

dbfSeed('schema.dbf', [['SKU', 'C', 6], ['NAME', 'C', 12], ['QTY', 'N', 4, 0], ['PRICE', 'N', 8, 2], ['ADDED', 'D'], ['ACTIVE', 'L']], [['A-100', 'Tea', 12, 19.90, '20261026', 'T'], ['B-200', 'Coffee', 0, 42.50, '20261025', 'F']]);
$db = dbfOpen('schema.dbf');
try {
    $header = dbase_get_header_info($db);
    if ($header === false) { throw new RuntimeException('Cannot read header'); }
    $columns = dbase_numfields($db); $count = dbase_numrecords($db);
    $actualNames = array_column($header, 'name');
    $expectedNames = ['SKU', 'NAME', 'QTY', 'PRICE', 'ADDED', 'ACTIVE'];
    if ($actualNames !== $expectedNames) { throw new RuntimeException('Unexpected columns'); }
    $rows = [];
    foreach ($header as $index => $field) {
        $rows[] = [$index, $field['name'], $field['type'], $field['length'], $field['precision'], $field['offset'], $field['format']];
    }
} finally { dbase_close($db); }
dbfReport(['Index', 'Name', 'Type', 'Bytes', 'Precision', 'Offset', 'Format'], $rows, ['fields' => $columns, 'records' => $count, 'schema_matches' => true]);
echo "schema.dbf: 6 fields, 2 records; schema accepted\n";

schema.dbf: 6 fields, 2 records; schema accepted

Offset первой колонки равен 1: перед ней расположен байт пометки удаления. PRICE: N, ширина 8, precision 2 оставляет место и для точки, и для знака. D возвращается строкой YYYYMMDD, не DateTime. Format форматирует, но не проверяет достоверность входа. Массив заголовка нельзя напрямую передать в create: структура определений другая. Полный перечень типов и ограничения приведены далее.

Пройти записи с единицы и вычислить общий остаток

Посчитаем общий остаток трёх товаров обычным for. Таблица показывает номер прочитанной записи и два индекса полученного PHP-массива. Результат — 19; товар с нулевым остатком не потерялся.

Что получится после повторного чтения

$row = dbase_get_record($db, 1);
$sku = rtrim($row[0], ' ');
$quantity = $row[1];

В DBF запись считается с 1, колонки PHP-массива — с 0. Поэтому get_record($db, 1) читает первый товар, а $row[0] содержит его SKU. Цикл начинает $number с 1, работает пока $number <= $count и увеличивает номер после прохода. $total += $row[1] прибавляет количество к сумме. numfields здесь равен 2, но count($row) был бы 3 из-за дополнительного deleted.

Открыть таблицу реального запуска · Скачать данные результата. HTML генерирует сама PHP-программа из прочитанных значений; для просмотра этой таблицы сервер не нужен.

Учебные DBF: stock.dbf.

<?php
declare(strict_types=1);
require __DIR__ . '/dbf105-helper.php';

dbfSeed('stock.dbf', [['SKU', 'C', 6], ['QTY', 'N', 4, 0]], [['A-100', 12], ['B-200', 0], ['C-300', 7]]);
$db = dbfOpen('stock.dbf');
try {
    $count = dbase_numrecords($db); $fieldCount = dbase_numfields($db);
    $rows = []; $total = 0;
    for ($number = 1; $number <= $count; $number++) {
        $row = dbase_get_record($db, $number);
        if ($row === false) { throw new RuntimeException('Cannot read stock'); }
        $rows[] = [$number, rtrim($row[0], ' '), $row[1]];
        $total += $row[1];
    }
} finally { dbase_close($db); }
dbfReport(['Record', 'row[0]: SKU', 'row[1]: QTY'], $rows, ['fields' => $fieldCount, 'total_qty' => $total]);
echo "stock.dbf: 3 records; total_qty=19\n";

stock.dbf: 3 records; total_qty=19

В этом файле пока нет помеченных удалёнными строк. При импорте существующего DBF проверяйте deleted перед суммированием, как показано в следующей главе. Номер записи — текущая позиция, не постоянный идентификатор. Полный проход читает n строк; это не SQL-агрегация и не индексный поиск. Большой файл лучше считать потоком без накопления всех строк в памяти и HTML.

Построить таблицу доступных товаров по именам столбцов

Менеджеру нужна таблица каталога: название, остаток, цена, дата и доступность заказа. Наше правило доступности: товар активен и количество больше нуля. Читаем поля по именам и формируем HTML из значений закрытого и повторно открытого products.dbf.

Что получится после повторного чтения

$item = dbase_get_record_with_names($db, 1);
$name = rtrim($item['NAME'], ' ');
$status = $item['ACTIVE'] && $item['QTY'] > 0 ? 'available' : 'unavailable';

get_record_with_names возвращает ассоциативный массив: $item["NAME"] понятнее $item[1]. && означает «оба условия истинны». N без дроби возвращается целым, PRICE — float, ADDED — строкой. Вход L: T/Y для истины, F/N для лжи, ? для неопределённого. В нашем реальном runtime PHP true при записи дал false после чтения; поэтому исходные значения намеренно "T" и "F". После чтения уже получаем bool для условий.

Открыть таблицу реального запуска · Скачать данные результата. HTML генерирует сама PHP-программа из прочитанных значений; для просмотра этой таблицы сервер не нужен.

Учебные DBF: products.dbf.

<?php
declare(strict_types=1);
require __DIR__ . '/dbf105-helper.php';

dbfSeed('products.dbf', [['SKU', 'C', 6], ['NAME', 'C', 12], ['QTY', 'N', 4, 0], ['PRICE', 'N', 8, 2], ['ADDED', 'D'], ['ACTIVE', 'L']], [['A-100', 'Tea', 12, 19.90, '20261026', 'T'], ['B-200', 'Coffee', 0, 42.50, '20261025', 'F']]);
$db = dbfOpen('products.dbf');
try {
    $rows = []; $available = 0; $count = dbase_numrecords($db);
    for ($number = 1; $number <= $count; $number++) {
        $item = dbase_get_record_with_names($db, $number);
        if ($item === false) { throw new RuntimeException('Cannot read item'); }
        $status = $item['ACTIVE'] && $item['QTY'] > 0 ? 'available' : 'unavailable';
        if ($status === 'available') { $available++; }
        $rows[] = [rtrim($item['SKU'], ' '), rtrim($item['NAME'], ' '), $item['QTY'], $item['PRICE'], $item['ADDED'], $item['ACTIVE'], $status];
    }
} finally { dbase_close($db); }
dbfReport(['SKU', 'Name', 'QTY', 'Price', 'Added', 'Active', 'Status'], $rows, ['available_products' => $available, 'logical_input' => 'T/F']);
echo "products.dbf: available=1; result.html contains 2 products\n";

products.dbf: available=1; result.html contains 2 products

Для HTML нужен htmlspecialchars; helper применяет его к каждому значению. Экранирование HTML не меняет кодировку DBF. deleted не равен нашему ACTIVE: выключенный товар и помеченная запись различаются. Не называйте колонку deleted для чтения по именам: ключ занят меткой. PRICE демонстрирует N с двумя знаками; float не обеспечивает точную десятичную арифметику. Денежные расчёты обычно ведут отдельно в целых минимальных единицах.

Передать кириллицу в Windows-1251 и проверить байты после чтения

Получатель ждёт Windows-1251, сайт работает в UTF-8. Если записать UTF-8 как есть, получатель может показать «кракозябры» независимо от кодировки страницы браузера. Сохраним Орех и Чай в согласованной кодировке, прочитаем обратно и покажем названия вместе с байтами.

Что получится после повторного чтения

$bytes = iconv('UTF-8', 'Windows-1251', $text);
if ($bytes === false || strlen($bytes) > 12) { throw new InvalidArgumentException('Text does not fit NAME'); }
$encoded[] = [$bytes];

Windows-1251 — договорённость с получателем, а не угадывание. iconv преобразует байты; strlen после преобразования измеряет размер для C-поля. Длинный текст отвергаем до записи: расширение может тихо обрезать его. bin2hex показывает байты без вывода неправильного UTF-8. Пример читает две записи и отдельно отказывает 13-байтному названию при лимите 12.

Открыть таблицу реального запуска · Скачать данные результата. HTML генерирует сама PHP-программа из прочитанных значений; для просмотра этой таблицы сервер не нужен.

Учебные DBF: names.dbf.

<?php
declare(strict_types=1);
require __DIR__ . '/dbf105-helper.php';

$input = ['Орех', 'Чай']; $encoded = [];
foreach ($input as $text) {
    $bytes = iconv('UTF-8', 'Windows-1251', $text);
    if ($bytes === false || strlen($bytes) > 12) { throw new InvalidArgumentException('Text does not fit NAME'); }
    $encoded[] = [$bytes];
}
dbfSeed('names.dbf', [['NAME', 'C', 12]], $encoded);
$db = dbfOpen('names.dbf');
try {
    $rows = [];
    for ($number = 1; $number <= dbase_numrecords($db); $number++) {
        $row = dbase_get_record($db, $number);
        if ($row === false) { throw new RuntimeException('Cannot read name'); }
        $stored = rtrim($row[0], ' ');
        $utf8 = iconv('Windows-1251', 'UTF-8', $stored);
        if ($utf8 === false) { throw new RuntimeException('Invalid agreed encoding'); }
        $rows[] = [$number, $utf8, strlen($stored), bin2hex($stored), strlen($row[0])];
    }
} finally { dbase_close($db); }
$tooLong = str_repeat('Я', 13);
$rejected = strlen(iconv('UTF-8', 'Windows-1251', $tooLong)) > 12;
dbfReport(['Record', 'UTF-8 name', 'Bytes without padding', 'Stored hex', 'Field bytes'], $rows, ['encoding' => 'Windows-1251', 'overlong_rejected_before_write' => $rejected]);
echo "names.dbf: Cyrillic round trip OK; 13-byte name rejected before write\n";

names.dbf: Cyrillic round trip OK; 13-byte name rejected before write

Кодировка не задаётся HTTP-заголовком или create. В API нет переключателя автоматического перекодирования. Языковой идентификатор в заголовке DBF может быть неполным или неверным; пример проверяет фактические байты, не обещает настройку всех внешних программ. Непредставимые emoji нельзя молча удалять через //IGNORE: нужен другой договор или отказ. Проверяйте false от iconv и сохраняйте предупреждение. Значимые хвостовые пробелы неотличимы от заполнения C-поля; rtrim здесь — осознанное правило названий.

Реальная задача из обсуждения Issue with Special Characters (ñ) in DBF File Generated by PHP: Поле DBF с буквой ñ показывается неверно, хотя HTML-ответ объявлен UTF-8. Здесь написано собственное решение для обозначенного учебного договора; вопрос служит источником ситуации, а правила API сверены с PHP/PECL.

Отличить неизвестное значение NULL от заполненной даты и числа

Для FoxPro неизвестная цена может отличаться от нулевой. Покажем nullable-поля и время: первая строка заполнена, во второй действительно NULL. Не подменяем неизвестность пустотой или числом 0.

Что получится после повторного чтения

$schema = [['CODE', 'C', 6, true], ['WHEN', 'T', true], ['PRICE', 'N', 8, 2, true], ['ACTIVE', 'L', true]];
dbfSeed('nullable.dbf', $schema, [['F-1', '20261026123045.123', 12.50, 'T'], [null, null, null, null]], DBASE_TYPE_FOXPRO);

Nullable поддерживается с dbase 7.0.0 для DBASE_TYPE_FOXPRO. true ставится после обычных аргументов типа: у C после длины, у N/F после длины и точности, у D/T/L сразу после буквы. Поэтому ["PRICE", "N", 8, 2, true] и ["ACTIVE", "L", true] имеют разную длину. T принимает YYYYMMDDhhmmss.uuu: 20261026123045.123 означает 26 октября 2026, 12:30:45 и 123 мс. В файле это специальное восьмибайтное представление, которое PHP возвращает строкой.

Открыть таблицу реального запуска · Скачать данные результата. HTML генерирует сама PHP-программа из прочитанных значений; для просмотра этой таблицы сервер не нужен.

Учебные DBF: nullable.dbf.

<?php
declare(strict_types=1);
require __DIR__ . '/dbf105-helper.php';

$schema = [['CODE', 'C', 6, true], ['WHEN', 'T', true], ['PRICE', 'N', 8, 2, true], ['ACTIVE', 'L', true]];
dbfSeed('nullable.dbf', $schema, [['F-1', '20261026123045.123', 12.50, 'T'], [null, null, null, null]], DBASE_TYPE_FOXPRO);
$db = dbfOpen('nullable.dbf');
try {
    $fieldCount = dbase_numfields($db); $rows = [];
    for ($number = 1; $number <= dbase_numrecords($db); $number++) {
        $row = dbase_get_record_with_names($db, $number);
        if ($row === false) { throw new RuntimeException('Cannot read nullable row'); }
        $rows[] = [$number, $row['CODE'] === null ? null : rtrim($row['CODE'], ' '), $row['WHEN'], $row['PRICE'], $row['ACTIVE']];
    }
} finally { dbase_close($db); }
dbfReport(['Record', 'Code', 'DateTime', 'Price', 'Active'], $rows, ['type' => DBASE_TYPE_FOXPRO, 'user_fields' => $fieldCount, 'null_is_not_zero' => $rows[1][3] === null]);
echo "nullable.dbf: 4 user fields; second record has 4 NULL values\n";

nullable.dbf: 4 user fields; second record has 4 NULL values

T не проверяет календарную корректность и не задаёт часовой пояс: это обязанности приложения. numfields показывает 4 пользовательских поля; физический FoxPro-заголовок содержит дополнительное _NullFlags, которое не надо добавлять к данным. Читатель обычного dBASE III может не поддержать вариант. PHP manual заявляет уровни DBF 3–5 и отдельно эти возможности FoxPro; это не обещание всех диалектов Visual FoxPro. Для старого DBF без NULL согласуйте отдельный признак отсутствия.

Пять констант расширения

Все пять констант доступны только при загруженном расширении, введены в dbase 7.0.0. В программе используйте имена, а не числа 0/2/3/48: они показывают назначение аргумента. Режим 1 не поддерживает нужное чтение заголовка. Версия PHP и DBASE_VERSION — разные версии.

Все типы полей и ограничения формата

Имена полей ограничены десятью символами в manual; реализация проверяет байтовую длину, поэтому для совместимого договора используйте ASCII до десяти байт. Nullable поддерживается у FoxPro с 7.0.0: флаг true следует после параметров конкретного типа. Null — отдельное состояние, не пустота и не ноль. Для D/T заранее проверьте дату, для C — кодировку и длину, для N/F — диапазон и формат; DBF не проверяет правила вашего бизнеса.

Блокировки, совместимость и границы применения

С dbase 7.0.0 расширение автоматически использует flock. Старое утверждение «блокировок нет» относится к более ранним версиям. Обычное чтение и запись получают соответствующий lock на время открытого ресурса; это может ожидать освобождения, поэтому не держите writer во время долгих сетевых запросов. На системах с блокировками уровня процесса многопоточный SAPI сохраняет особый риск, указанный PHP manual. Другой инструмент должен соблюдать совместимый протокол блокировок; несколько операций не становятся SQL-транзакцией.

Учебные DBF лежат в отдельной папке; реальный вход импортёра копируйте в контролируемый путь и ограничивайте размер. Файл не должен быть одновременно переписываем поставщиком. Проверяйте схему, кодировку и значения перед записью. Для сайта с конкурентными обновлениями выбирайте SQLite или SQL через PDO. Для маленького файлового словаря «ключ → строка» посмотрите DBA и его конкретные handlers.

Все функции dBase: перейти к контракту

Ниже — все 12 функций расширения, сгруппированные по жизненному циклу: создание/открытие/закрытие, схема и чтение, добавление/замена/удаление/уплотнение. У каждой карточки есть параметры, результат, отказы, ограничения и две ссылки на самостоятельные программы. Все программы создают собственные входные DBF: чужой /tmp/test.dbf заранее не требуется.