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

<?php
declare(strict_types=1);
require __DIR__.'/lab.php';
$db=null;$owned=$removed=$rows=$checks=$observations=[];
try {
    $config=f155Config();$db=f155Connect($config);$runtime=f155Runtime($db,$config);

    function createBlob155($context) {
        $call=f155Capture(static fn()=>ibase_blob_create($context));
        if (!is_resource($call['value']) || $call['warning']) {f155Failure('BLOB не создан',$call);}
        return $call['value'];
    }
    function appendBlob155($handle,string $bytes): void {
        $call=f155Capture(static fn()=>ibase_blob_add($handle,$bytes));
        // Successful add has no value (null), not true. Check refusal and diagnostics.
        if ($call['value']===false || $call['warning'] || $call['code']!==0) {f155Failure('Порция BLOB не записана',$call);}
    }
    function finishBlob155(&$handle): string {
        $call=f155Capture(static fn()=>ibase_blob_close($handle));
        if (!is_string($call['value']) || $call['warning']) {f155Failure('BLOB не закрыт',$call);}
        $handle=null;
        return $call['value'];
    }
    function discardBlob155(&$handle): bool {
        $call=f155Capture(static fn()=>ibase_blob_cancel($handle));
        if ($call['value']!==true || $call['warning']) {f155Failure('Незавершённый BLOB не отменён',$call);}
        $handle=null;
        return true;
    }
    function inspectBlob155($context,string $id,bool $keepSmallText=false): array {
        $call=f155Capture(static fn()=>ibase_blob_open($context,$id));
        if (!is_resource($call['value']) || $call['warning']) {f155Failure('Сохранённый BLOB не открыт',$call);}
        $reader=$call['value'];unset($call);
        $bytes=0;$value='';$hash=hash_init('sha256');
        try {
            while (true) {
                $call=f155Capture(static fn()=>ibase_blob_get($reader,8192));
                if (!is_string($call['value']) || $call['warning']) {f155Failure('BLOB не прочитан',$call);}
                $chunk=$call['value'];
                if ($chunk==='') {break;}
                $bytes+=strlen($chunk);hash_update($hash,$chunk);
                if ($keepSmallText) {
                    if ($bytes>4096) {throw new RuntimeException('Учебный текст превышает лимит 4096 байт.');}
                    $value.=$chunk;
                }
            }
        } finally {
            $closed=f155Capture(static fn()=>ibase_blob_close($reader));$reader=null;
            if ($closed['value']===false || $closed['warning']) {f155Failure('Читающий BLOB не закрыт',$closed);}
        }
        return ['bytes'=>$bytes,'sha256'=>hash_final($hash),'text'=>$value];
    }

    $name=f155OwnTable($db,$owned,'note','(order_id INTEGER NOT NULL PRIMARY KEY,note_text BLOB SUB_TYPE TEXT CHARACTER SET UTF8)');
    $q=f155Qualified($name);

    $note='Оставить коробки у стойки выдачи.';
    $writer=createBlob155($db);
    try {
        appendBlob155($writer,$note);
        $id=finishBlob155($writer);
        f155Command($db,"INSERT INTO $q(order_id,note_text) VALUES(?,?)",[155,$id]);
        f155Commit($db);
    } finally {
        if (is_resource($writer)) {discardBlob155($writer);}
    }
    $record=f155Read($db,"SELECT order_id AS \"order_id\",note_text AS \"blob_id\" FROM $q WHERE order_id=?",[155])[0];
    $saved=inspectBlob155($db,$record['blob_id'],true);
    $rows=[['Заказ',$record['order_id']],['Примечание после commit',$saved['text']],['Байт UTF-8',$saved['bytes']],
        ['В строке хранится BLOB ID',is_string($record['blob_id'])],['Прочитанный текст совпал',$saved['text']===$note]];
    $checks=['order_found'=>$record['order_id']===155,'writer_closed'=>$writer===null,
        'blob_id_saved'=>is_string($record['blob_id'])&&$record['blob_id']!=='',
        'text_roundtrip'=>$saved['text']===$note,'byte_count'=>$saved['bytes']===strlen($note),
        'content_hash'=>$saved['sha256']===hash('sha256',$note)];
    $observations=['order_id'=>$record['order_id'],'source_text'=>$note,'saved_text'=>$saved['text'],'source_bytes'=>strlen($note),
        'saved_bytes'=>$saved['bytes'],'sha256'=>$saved['sha256'],'id_is_content'=>$record['blob_id']===$note];

} finally {
    if (is_resource($db)) {try {$removed=f155Cleanup($db,$owned);} finally {ibase_close($db);}}
}

f155Report('fb155-text-note','Примечание к заказу: сохранить текст и прочитать его после commit',$rows,$checks,$observations,$runtime,$owned,$removed);

Заказ — 155
Примечание после commit — Оставить коробки у стойки выдачи.
Байт UTF-8 — 61
В строке хранится BLOB ID — да
Прочитанный текст совпал — да

Самостоятельный CLI-пример содержит lab.php и README, создаёт одну собственную таблицу, сохраняет и заново читает данные Firebird, формирует result.html/result.json и удаляет свою таблицу. В примере импорта также приложен настоящий invoice.txt.

<?php
declare(strict_types=1);
require __DIR__.'/lab.php';
$db=null;$owned=$removed=$rows=$checks=$observations=[];
try {
    $config=f155Config();$db=f155Connect($config);$runtime=f155Runtime($db,$config);

    function createBlob155($context) {
        $call=f155Capture(static fn()=>ibase_blob_create($context));
        if (!is_resource($call['value']) || $call['warning']) {f155Failure('BLOB не создан',$call);}
        return $call['value'];
    }
    function appendBlob155($handle,string $bytes): void {
        $call=f155Capture(static fn()=>ibase_blob_add($handle,$bytes));
        // Successful add has no value (null), not true. Check refusal and diagnostics.
        if ($call['value']===false || $call['warning'] || $call['code']!==0) {f155Failure('Порция BLOB не записана',$call);}
    }
    function finishBlob155(&$handle): string {
        $call=f155Capture(static fn()=>ibase_blob_close($handle));
        if (!is_string($call['value']) || $call['warning']) {f155Failure('BLOB не закрыт',$call);}
        $handle=null;
        return $call['value'];
    }
    function discardBlob155(&$handle): bool {
        $call=f155Capture(static fn()=>ibase_blob_cancel($handle));
        if ($call['value']!==true || $call['warning']) {f155Failure('Незавершённый BLOB не отменён',$call);}
        $handle=null;
        return true;
    }
    function inspectBlob155($context,string $id,bool $keepSmallText=false): array {
        $call=f155Capture(static fn()=>ibase_blob_open($context,$id));
        if (!is_resource($call['value']) || $call['warning']) {f155Failure('Сохранённый BLOB не открыт',$call);}
        $reader=$call['value'];unset($call);
        $bytes=0;$value='';$hash=hash_init('sha256');
        try {
            while (true) {
                $call=f155Capture(static fn()=>ibase_blob_get($reader,8192));
                if (!is_string($call['value']) || $call['warning']) {f155Failure('BLOB не прочитан',$call);}
                $chunk=$call['value'];
                if ($chunk==='') {break;}
                $bytes+=strlen($chunk);hash_update($hash,$chunk);
                if ($keepSmallText) {
                    if ($bytes>4096) {throw new RuntimeException('Учебный текст превышает лимит 4096 байт.');}
                    $value.=$chunk;
                }
            }
        } finally {
            $closed=f155Capture(static fn()=>ibase_blob_close($reader));$reader=null;
            if ($closed['value']===false || $closed['warning']) {f155Failure('Читающий BLOB не закрыт',$closed);}
        }
        return ['bytes'=>$bytes,'sha256'=>hash_final($hash),'text'=>$value];
    }

    $name=f155OwnTable($db,$owned,'binary','(attachment_id INTEGER NOT NULL PRIMARY KEY,file_name VARCHAR(80) NOT NULL,payload BLOB SUB_TYPE BINARY)');
    $q=f155Qualified($name);

    // Only fixture preparation: a tiny repeatable device record, including NUL and 0xFF.
    // In the application this is fopen($validatedTemporaryUpload,'rb').
    $input=tmpfile();
    if ($input===false) {throw new RuntimeException('Не создан временный учебный файл.');}
    $writer=null;$sourceHash=hash_init('sha256');$sourceBytes=0;$writes=0;
    try {
        $block=str_repeat("PACKET\0\xFF\x10\n",300);
        for ($part=0;$part<30;$part++) {
            if (fwrite($input,$block)!==strlen($block)) {throw new RuntimeException('Учебный файл записан не полностью.');}
        }
        if (rewind($input)!==true) {throw new RuntimeException('Не удалось вернуться к началу файла.');}
        $writer=createBlob155($db);
        while (!feof($input)) {
            $chunk=fread($input,8192);
            if ($chunk===false) {throw new RuntimeException('Ошибка чтения входного файла.');}
            if ($chunk==='') {break;}
            appendBlob155($writer,$chunk);
            $sourceBytes+=strlen($chunk);hash_update($sourceHash,$chunk);$writes++;
        }
        $id=finishBlob155($writer);
        f155Command($db,"INSERT INTO $q(attachment_id,file_name,payload) VALUES(?,?,?)",[201,'scanner-packets.bin',$id]);
        f155Commit($db);
    } finally {
        if (is_resource($writer)) {discardBlob155($writer);}
        fclose($input);$input=null;
    }
    $sourceSha=hash_final($sourceHash);
    $record=f155Read($db,"SELECT file_name AS \"file_name\",payload AS \"blob_id\" FROM $q WHERE attachment_id=?",[201])[0];
    $saved=inspectBlob155($db,$record['blob_id']);
    $rows=[['Вложение',$record['file_name']],['Байт исходного файла',$sourceBytes],['Вызовов добавления',$writes],
        ['Байт прочитано из BLOB',$saved['bytes']],['SHA-256',$saved['sha256']],['Байты и SHA-256 совпали',$saved['bytes']===$sourceBytes&&$saved['sha256']===$sourceSha]];
    $checks=['source_fixture_size'=>$sourceBytes===90000,'bounded_chunk_writes'=>$writes===11,'writer_closed'=>$writer===null,
        'binary_byte_count'=>$saved['bytes']===$sourceBytes,'binary_hash'=>$saved['sha256']===$sourceSha,
        'no_full_readback_buffer'=>$saved['text']===''];
    $observations=['fixture_record_hex'=>'5041434b455400ff100a','fixture_records'=>9000,'chunk_bytes'=>8192,
        'source_bytes'=>$sourceBytes,'source_sha256'=>$sourceSha,'saved_bytes'=>$saved['bytes'],'saved_sha256'=>$saved['sha256'],
        'write_calls'=>$writes,'text_buffer_used'=>false];

} finally {
    if (is_resource($db)) {try {$removed=f155Cleanup($db,$owned);} finally {ibase_close($db);}}
}

f155Report('fb155-chunked-attachment','Двоичное вложение: записать порциями и сверить все 90000 байт',$rows,$checks,$observations,$runtime,$owned,$removed);

Вложение — scanner-packets.bin
Байт исходного файла — 90000
Вызовов добавления — 11
Байт прочитано из BLOB — 90000
SHA-256 — fe792f8cbc151d3279a058045af4862f8b74f0ba8d5a31d01f311b0b89b7e789
Байты и SHA-256 совпали — да

Самостоятельный CLI-пример содержит lab.php и README, создаёт одну собственную таблицу, сохраняет и заново читает данные Firebird, формирует result.html/result.json и удаляет свою таблицу. В примере импорта также приложен настоящий invoice.txt.

<?php
declare(strict_types=1);
require __DIR__.'/lab.php';
$db=null;$owned=$removed=$rows=$checks=$observations=[];
try {
    $config=f155Config();$db=f155Connect($config);$runtime=f155Runtime($db,$config);

    function createBlob155($context) {
        $call=f155Capture(static fn()=>ibase_blob_create($context));
        if (!is_resource($call['value']) || $call['warning']) {f155Failure('BLOB не создан',$call);}
        return $call['value'];
    }
    function appendBlob155($handle,string $bytes): void {
        $call=f155Capture(static fn()=>ibase_blob_add($handle,$bytes));
        // Successful add has no value (null), not true. Check refusal and diagnostics.
        if ($call['value']===false || $call['warning'] || $call['code']!==0) {f155Failure('Порция BLOB не записана',$call);}
    }
    function finishBlob155(&$handle): string {
        $call=f155Capture(static fn()=>ibase_blob_close($handle));
        if (!is_string($call['value']) || $call['warning']) {f155Failure('BLOB не закрыт',$call);}
        $handle=null;
        return $call['value'];
    }
    function discardBlob155(&$handle): bool {
        $call=f155Capture(static fn()=>ibase_blob_cancel($handle));
        if ($call['value']!==true || $call['warning']) {f155Failure('Незавершённый BLOB не отменён',$call);}
        $handle=null;
        return true;
    }
    function inspectBlob155($context,string $id,bool $keepSmallText=false): array {
        $call=f155Capture(static fn()=>ibase_blob_open($context,$id));
        if (!is_resource($call['value']) || $call['warning']) {f155Failure('Сохранённый BLOB не открыт',$call);}
        $reader=$call['value'];unset($call);
        $bytes=0;$value='';$hash=hash_init('sha256');
        try {
            while (true) {
                $call=f155Capture(static fn()=>ibase_blob_get($reader,8192));
                if (!is_string($call['value']) || $call['warning']) {f155Failure('BLOB не прочитан',$call);}
                $chunk=$call['value'];
                if ($chunk==='') {break;}
                $bytes+=strlen($chunk);hash_update($hash,$chunk);
                if ($keepSmallText) {
                    if ($bytes>4096) {throw new RuntimeException('Учебный текст превышает лимит 4096 байт.');}
                    $value.=$chunk;
                }
            }
        } finally {
            $closed=f155Capture(static fn()=>ibase_blob_close($reader));$reader=null;
            if ($closed['value']===false || $closed['warning']) {f155Failure('Читающий BLOB не закрыт',$closed);}
        }
        return ['bytes'=>$bytes,'sha256'=>hash_final($hash),'text'=>$value];
    }

    $name=f155OwnTable($db,$owned,'invoice','(invoice_id INTEGER NOT NULL PRIMARY KEY,file_name VARCHAR(80) NOT NULL,body BLOB SUB_TYPE BINARY)');
    $q=f155Qualified($name);

    $path=__DIR__.'/invoice.txt';
    $input=fopen($path,'rb');
    if ($input===false) {throw new RuntimeException('Учебная накладная не открыта.');}
    try {
        // Freshly opened stream is at byte 0. Import consumes from its current position.
        $call=f155Capture(static fn()=>ibase_blob_import($db,$input));
        if (!is_string($call['value']) || $call['warning'] || $call['code']!==0) {f155Failure('Накладная не импортирована',$call);}
        $id=$call['value'];
        $fileStillOpen=is_resource($input);$position=ftell($input);
    } finally {fclose($input);$input=null;}
    f155Command($db,"INSERT INTO $q(invoice_id,file_name,body) VALUES(?,?,?)",[155,'invoice.txt',$id]);
    f155Commit($db);
    $record=f155Read($db,"SELECT invoice_id AS \"invoice_id\",file_name AS \"file_name\",body AS \"blob_id\" FROM $q WHERE invoice_id=?",[155])[0];
    $saved=inspectBlob155($db,$record['blob_id'],true);
    $expected=file_get_contents($path);
    if ($expected===false) {throw new RuntimeException('Исходная накладная недоступна для сравнения.');}
    $rows=[['Накладная',$record['invoice_id']],['Имя файла',$record['file_name']],['Прочитано байт',$saved['bytes']],
        ['Текст из базы',$saved['text']],['После import файл ещё был открыт',$fileStillOpen],['Весь файл совпал',$saved['text']===$expected]];
    $checks=['invoice_found'=>$record['invoice_id']===155,'import_returned_id'=>is_string($id)&&$id!=='',
        'import_consumed_file'=>$position===strlen($expected),'caller_owns_file'=>$fileStillOpen&&$input===null,
        'file_roundtrip'=>$saved['text']===$expected,'file_hash'=>$saved['sha256']===hash('sha256',$expected)];
    $observations=['file_name'=>'invoice.txt','source_bytes'=>strlen($expected),'saved_bytes'=>$saved['bytes'],'text'=>$saved['text'],
        'sha256'=>$saved['sha256'],'stream_position_after_import'=>$position,'file_was_open_after_import'=>$fileStillOpen];

} finally {
    if (is_resource($db)) {try {$removed=f155Cleanup($db,$owned);} finally {ibase_close($db);}}
}

f155Report('fb155-import-file','Накладная из файла: импортировать содержимое и сохранить связь с заказом',$rows,$checks,$observations,$runtime,$owned,$removed);

Накладная — 155
Имя файла — invoice.txt
Прочитано байт — 97
Текст из базы — Накладная №155
Кабель USB-C; 3 шт.
Получатель: мастерская

После import файл ещё был открыт — да
Весь файл совпал — да

Самостоятельный CLI-пример содержит lab.php и README, создаёт одну собственную таблицу, сохраняет и заново читает данные Firebird, формирует result.html/result.json и удаляет свою таблицу. В примере импорта также приложен настоящий invoice.txt.

<?php
declare(strict_types=1);
require __DIR__.'/lab.php';
$db=null;$owned=$removed=$rows=$checks=$observations=[];
try {
    $config=f155Config();$db=f155Connect($config);$runtime=f155Runtime($db,$config);

    function createBlob155($context) {
        $call=f155Capture(static fn()=>ibase_blob_create($context));
        if (!is_resource($call['value']) || $call['warning']) {f155Failure('BLOB не создан',$call);}
        return $call['value'];
    }
    function appendBlob155($handle,string $bytes): void {
        $call=f155Capture(static fn()=>ibase_blob_add($handle,$bytes));
        // Successful add has no value (null), not true. Check refusal and diagnostics.
        if ($call['value']===false || $call['warning'] || $call['code']!==0) {f155Failure('Порция BLOB не записана',$call);}
    }
    function finishBlob155(&$handle): string {
        $call=f155Capture(static fn()=>ibase_blob_close($handle));
        if (!is_string($call['value']) || $call['warning']) {f155Failure('BLOB не закрыт',$call);}
        $handle=null;
        return $call['value'];
    }
    function discardBlob155(&$handle): bool {
        $call=f155Capture(static fn()=>ibase_blob_cancel($handle));
        if ($call['value']!==true || $call['warning']) {f155Failure('Незавершённый BLOB не отменён',$call);}
        $handle=null;
        return true;
    }
    function inspectBlob155($context,string $id,bool $keepSmallText=false): array {
        $call=f155Capture(static fn()=>ibase_blob_open($context,$id));
        if (!is_resource($call['value']) || $call['warning']) {f155Failure('Сохранённый BLOB не открыт',$call);}
        $reader=$call['value'];unset($call);
        $bytes=0;$value='';$hash=hash_init('sha256');
        try {
            while (true) {
                $call=f155Capture(static fn()=>ibase_blob_get($reader,8192));
                if (!is_string($call['value']) || $call['warning']) {f155Failure('BLOB не прочитан',$call);}
                $chunk=$call['value'];
                if ($chunk==='') {break;}
                $bytes+=strlen($chunk);hash_update($hash,$chunk);
                if ($keepSmallText) {
                    if ($bytes>4096) {throw new RuntimeException('Учебный текст превышает лимит 4096 байт.');}
                    $value.=$chunk;
                }
            }
        } finally {
            $closed=f155Capture(static fn()=>ibase_blob_close($reader));$reader=null;
            if ($closed['value']===false || $closed['warning']) {f155Failure('Читающий BLOB не закрыт',$closed);}
        }
        return ['bytes'=>$bytes,'sha256'=>hash_final($hash),'text'=>$value];
    }

    $name=f155OwnTable($db,$owned,'accepted','(upload_id INTEGER NOT NULL PRIMARY KEY,file_name VARCHAR(80) NOT NULL,payload BLOB SUB_TYPE BINARY)');
    $q=f155Qualified($name);

    $limit=16;$acceptedBytes=0;$cancelled=false;$reason='';
    $writer=createBlob155($db);
    try {
        foreach (['DRAFT-PART-1','DRAFT-PART-2'] as $chunk) {
            if ($acceptedBytes+strlen($chunk)>$limit) {
                $reason='Размер превышает учебный лимит 16 байт';
                $cancelled=discardBlob155($writer);
                break;
            }
            appendBlob155($writer,$chunk);$acceptedBytes+=strlen($chunk);
        }
        if (!$cancelled) {throw new LogicException('Учебный черновик должен быть отклонён.');}
    } finally {if (is_resource($writer)) {discardBlob155($writer);}}
    // No close/ID/INSERT for the rejected file. Cancel does not roll back other SQL.
    $before=f155Read($db,"SELECT COUNT(*) AS \"found\" FROM $q")[0]['found'];
    $accepted='3 коробки';
    if (strlen($accepted)>$limit) {throw new DomainException('Исправленное примечание тоже превышает лимит.');}
    $writer=createBlob155($db);
    try {
        appendBlob155($writer,$accepted);
        $id=finishBlob155($writer);
        f155Command($db,"INSERT INTO $q(upload_id,file_name,payload) VALUES(?,?,?)",[2,'accepted-note.txt',$id]);
        f155Commit($db);
    } finally {if (is_resource($writer)) {discardBlob155($writer);}}
    $savedRows=f155Read($db,"SELECT upload_id AS \"upload_id\",file_name AS \"file_name\",payload AS \"blob_id\" FROM $q ORDER BY upload_id");
    $saved=inspectBlob155($db,$savedRows[0]['blob_id'],true);
    $rows=[['Причина отказа',$reason],['До отказа записано байт',$acceptedBytes],['Незавершённый BLOB отменён',$cancelled],
        ['Строк после отказа',$before],['Принятый файл',$savedRows[0]['file_name']],['Текст принятой записи',$saved['text']],['Всего принятых записей',count($savedRows)]];
    $checks=['limit_detected'=>$reason!=='','first_chunk_was_written'=>$acceptedBytes===12,'unfinished_blob_cancelled'=>$cancelled,
        'no_rejected_row'=>$before===0,'only_accepted_row'=>count($savedRows)===1&&$savedRows[0]['upload_id']===2,
        'accepted_payload'=>$saved['text']===$accepted,'accepted_within_limit'=>strlen($accepted)<=$limit,'writer_closed'=>$writer===null];
    $observations=['draft_limit_bytes'=>$limit,'draft_written_bytes'=>$acceptedBytes,'cancelled'=>$cancelled,'rows_after_rejection'=>$before,
        'accepted_ids'=>array_column($savedRows,'upload_id'),'accepted_name'=>$savedRows[0]['file_name'],'accepted_text'=>$saved['text']];

} finally {
    if (is_resource($db)) {try {$removed=f155Cleanup($db,$owned);} finally {ibase_close($db);}}
}

f155Report('fb155-cancel-upload','Отклонить незавершённое вложение и сохранить исправленное',$rows,$checks,$observations,$runtime,$owned,$removed);

Причина отказа — Размер превышает учебный лимит 16 байт
До отказа записано байт — 12
Незавершённый BLOB отменён — да
Строк после отказа — 0
Принятый файл — accepted-note.txt
Текст принятой записи — 3 коробки
Всего принятых записей — 1

Самостоятельный CLI-пример содержит lab.php и README, создаёт одну собственную таблицу, сохраняет и заново читает данные Firebird, формирует result.html/result.json и удаляет свою таблицу. В примере импорта также приложен настоящий invoice.txt.