Membuat Tool Membaca File AI Agent PHP

Terakhir diperbarui: 22 Agustus 2026

Instalasi Library Parsing File di PHP

Untuk membaca dokumen biner seperti PDF dan DOCX secara native tanpa ketergantungan utility sistem operasi luar, pasang library parser standar industri melalui Composer:

composer require smalot/pdfparser phpoffice/phpword

{
  "name": "infokoding/ai-agent-file-tools",
  "description": "Enterprise File Reader Tools (PDF, DOCX, CSV, JSON) for PHP AI Agents",
  "type": "project",
  "require": {
    "php": ">=8.2",
    "smalot/pdfparser": "^2.11",
    "phpoffice/phpword": "^1.3",
    "guzzlehttp/guzzle": "^7.9"
  },
  "autoload": {
    "psr-4": {
      "App\": "src/"
    }
  },
  "config": {
    "optimize-autoloader": true,
    "sort-packages": true,
    "allow-plugins": {}
  }
}

Diagram Arsitektur: Proteksi Path Traversal & Pipeline Ekstraksi FileTool

WebP Lossless • 65 KB • Schema Ready

Implementasi FileTool Class untuk AI Agent PHP

Berikut adalah implementasi class FileTool berbasis ToolInterface yang mengintegrasikan 4 lapis perlindungan keamanan path traversal, pemangkasan buffer token, dan multi-format document parser:

<?php

namespace App\Tools;

class FileTool implements ToolInterface
{
    private string $allowedDir;
    private int $maxFileSizeBytes;
    private int $maxChars;

    public function __construct(
        string $allowedDir = './uploads',
        int $maxFileSizeMB = 10,
        int $maxChars = 8000
    ) {
        $this->allowedDir       = realpath($allowedDir) ?: $allowedDir;
        $this->maxFileSizeBytes = $maxFileSizeMB * 1024 * 1024;
        $this->maxChars         = $maxChars;
    }

    public function getDefinition(): array
    {
        return [
            'type'     => 'function',
            'function' => [
                'name'        => 'read_file',
                'description' => 'Membaca dan mengekstrak teks isi file lokal (PDF, TXT, CSV, JSON, DOCX). Masukkan nama file yang tersimpan di server.',
                'parameters'  => [
                    'type'       => 'object',
                    'properties' => [
                        'filename' => [
                            'type'        => 'string',
                            'description' => 'Nama file dokumen yang ingin dibaca (misal: laporan-keuangan.pdf, data.csv).',
                        ],
                    ],
                    'required' => ['filename'],
                ],
            ],
        ];
    }

    public function execute(array $args): mixed
    {
        // Lapisan Keamanan 1: Sanitasi nama file dengan basename()
        $filename = basename(trim($args['filename'] ?? ''));
        if (empty($filename)) {
            return ['status' => 'error', 'message' => 'Nama file tidak boleh kosong.'];
        }

        $filepath = $this->allowedDir . DIRECTORY_SEPARATOR . $filename;

        // Lapisan Keamanan 2: Validasi realpath terhadap direktori yang diizinkan (Jail Check)
        $realPath = realpath($filepath);
        if (!$realPath || !str_starts_with($realPath, $this->allowedDir)) {
            return ['status' => 'error', 'message' => 'Akses file ditolak: path berada di luar direktori yang diizinkan.'];
        }

        if (!file_exists($realPath) || !is_readable($realPath)) {
            return ['status' => 'error', 'message' => "File '{$filename}' tidak ditemukan atau tidak dapat dibaca."];
        }

        // Lapisan Keamanan 3: Pembatasan ukuran file fisik
        if (filesize($realPath) > $this->maxFileSizeBytes) {
            $maxMB = $this->maxFileSizeBytes / 1024 / 1024;
            return ['status' => 'error', 'message' => "Ukuran file melebihi batas maksimum {$maxMB}MB."];
        }

        $extension = strtolower(pathinfo($realPath, PATHINFO_EXTENSION));

        try {
            $text = match ($extension) {
                'txt'  => file_get_contents($realPath),
                'json' => $this->readJson($realPath),
                'csv'  => $this->readCsv($realPath),
                'pdf'  => $this->readPdf($realPath),
                'docx' => $this->readDocx($realPath),
                default => null,
            };
        } catch (\Throwable $e) {
            return ['status' => 'error', 'message' => 'Gagal memproses file: ' . $e->getMessage()];
        }

        if ($text === null) {
            return ['status' => 'error', 'message' => "Ekstensi file '.{$extension}' tidak didukung."];
        }

        // Lapisan Keamanan 4: Pemotongan buffer token teks
        $isTruncated = false;
        if (strlen($text) > $this->maxChars) {
            $text        = substr($text, 0, $this->maxChars) . "\n...[Teks terpotong karena melebihi batas token buffer]";
            $isTruncated = true;
        }

        return [
            'status'       => 'success',
            'filename'     => $filename,
            'extension'    => $extension,
            'characters'   => strlen($text),
            'is_truncated' => $isTruncated,
            'content'      => $text,
        ];
    }

    private function readJson(string $path): string
    {
        $content = file_get_contents($path);
        $data    = json_decode($content, true);
        return json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
    }

    private function readCsv(string $path): string
    {
        $lines = [];
        if (($handle = fopen($path, 'r')) !== false) {
            while (($row = fgetcsv($handle, 1000, ',')) !== false) {
                $lines[] = implode(' | ', $row);
            }
            fclose($handle);
        }
        return implode("\n", $lines);
    }

    private function readPdf(string $path): string
    {
        if (!class_exists('\Smalot\PdfParser\Parser')) {
            throw new \RuntimeException('Library smalot/pdfparser belum terpasang.');
        }
        $parser = new \Smalot\PdfParser\Parser();
        $pdf    = $parser->parseFile($path);
        return $pdf->getText();
    }

    private function readDocx(string $path): string
    {
        if (!class_exists('\PhpOffice\PhpWord\IOFactory')) {
            throw new \RuntimeException('Library phpoffice/phpword belum terpasang.');
        }
        $phpWord  = \PhpOffice\PhpWord\IOFactory::load($path);
        $sections = $phpWord->getSections();
        $text     = '';
        foreach ($sections as $section) {
            foreach ($section->getElements() as $element) {
                if (method_exists($element, 'getText')) {
                    $text .= $element->getText() . "\n";
                }
            }
        }
        return $text;
    }
}

Integrasi FileTool ke dalam AI Agent PHP Loop

Berikut adalah contoh skrip eksekusi pengujian membaca laporan penjualan PDF:

<?php
// run-agent-file.php

require_once __DIR__ . '/vendor/autoload.php';

use App\OpenAIClient;
use App\Agent\Agent;
use App\Tools\FileTool;

$client = new OpenAIClient(getenv('OPENAI_API_KEY'));
$agent  = new Agent($client, maxIterations: 5);

// Registrasikan FileTool dengan direktori uploads
$agent->registerTool(new FileTool(allowedDir: __DIR__ . '/uploads', maxFileSizeMB: 10, maxChars: 8000));

// Instruksi membaca dokumen
$prompt = 'Baca file "laporan-penjualan-q3.pdf", kemudian buatkan ringkasan 3 poin utama keuntungan perusahaan.';
$response = $agent->run($prompt);

echo "Hasil Analisis AI Agent:\n" . $response . "\n";

Penanganan Dokumen Besar (>10MB): Direct FileTool vs Streaming Chunking RAG

Membaca dokumen masif berukuran puluhan megabyte (seperti laporan tahunan 200 halaman atau log server 50MB) secara utuh ke dalam memori PHP akan memicu batas memory_limit dan melampaui kapasitas context window model AI. Berikut adalah strategi perbandingan arsitektural untuk menangani file besar:

FAQ: Pertanyaan Seputar Tool Membaca File AI Agent PHP