From 7c5b6c60eed5bdcc1902695cd91a01c5be6cab52 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alejandro=20Uribe=20S=C3=A1nchez?=
 <alejouribesanchez@gmail.com>
Date: Wed, 26 Nov 2025 15:55:32 -0500
Subject: [PATCH] Add split and classify document support to Client

Introduces traits and methods for processing and retrieving split and classified documents via base64 and URL in the Client class. Adds corresponding tests for split and classify document functionality. Also updates the User-Agent string in request headers.
---
 src/veryfi/Client.php                         |  25 ++--
 .../ProcessClassifyDocumentBase64.php         |  24 ++++
 .../classify/ProcessClassifyDocumentUrl.php   |  24 ++++
 src/veryfi/client/GetHeaders.php              |   2 +-
 src/veryfi/split/GetSplitDocument.php         |  20 ++++
 src/veryfi/split/GetSplitDocuments.php        |  24 ++++
 .../split/ProcessSplitDocumentBase64.php      |  24 ++++
 src/veryfi/split/ProcessSplitDocumentUrl.php  |  24 ++++
 tests/ClientClassifyDocumentsTest.php         |  59 ++++++++++
 tests/ClientSplitDocumentsTest.php            | 111 ++++++++++++++++++
 10 files changed, 328 insertions(+), 9 deletions(-)
 create mode 100644 src/veryfi/classify/ProcessClassifyDocumentBase64.php
 create mode 100644 src/veryfi/classify/ProcessClassifyDocumentUrl.php
 create mode 100644 src/veryfi/split/GetSplitDocument.php
 create mode 100644 src/veryfi/split/GetSplitDocuments.php
 create mode 100644 src/veryfi/split/ProcessSplitDocumentBase64.php
 create mode 100644 src/veryfi/split/ProcessSplitDocumentUrl.php
 create mode 100644 tests/ClientClassifyDocumentsTest.php
 create mode 100644 tests/ClientSplitDocumentsTest.php

diff --git a/src/veryfi/Client.php b/src/veryfi/Client.php
index b9bbd46..a375fe0 100644
--- a/src/veryfi/Client.php
+++ b/src/veryfi/Client.php
@@ -72,6 +72,12 @@
 use veryfi\documents\lineitems\GetLineItem;
 use veryfi\documents\lineitems\GetLineItems;
 use veryfi\documents\lineitems\UpdateLineItem;
+use veryfi\split\GetSplitDocument;
+use veryfi\split\GetSplitDocuments;
+use veryfi\split\ProcessSplitDocumentBase64;
+use veryfi\split\ProcessSplitDocumentUrl;
+use veryfi\classify\ProcessClassifyDocumentBase64;
+use veryfi\classify\ProcessClassifyDocumentUrl;
 
 
 
@@ -143,14 +149,15 @@ class Client
      * @param string $api_version Api version to use Veryfi, currently v8
      * @param int $api_timeout Api timeout for call Veryfi api, by default 120
      */
-    public function __construct(string $client_id,
-                                string $client_secret,
-                                string $username,
-                                string $api_key,
-                                string $base_url = 'https://api.veryfi.com/api/',
-                                string $api_version = 'v8',
-                                int    $api_timeout = 120)
-    {
+    public function __construct(
+        string $client_id,
+        string $client_secret,
+        string $username,
+        string $api_key,
+        string $base_url = 'https://api.veryfi.com/api/',
+        string $api_version = 'v8',
+        int $api_timeout = 120
+    ) {
         $this->client_id = $client_id;
         $this->client_secret = $client_secret;
         $this->username = $username;
@@ -173,5 +180,7 @@ public function __construct(string $client_id,
     use DeleteW8BENE, GetW8BENE, GetW8BENEs, ProcessW8BENE, ProcessW8BENEBase64, ProcessW8BENEUrl;
     use DeleteW9, GetW9, GetW9s, ProcessW9, ProcessW9Base64, ProcessW9Url;
     use AddLineItem, DeleteLineItem, DeleteLineItems, GetLineItem, GetLineItems, UpdateLineItem;
+    use GetSplitDocument, GetSplitDocuments, ProcessSplitDocumentBase64, ProcessSplitDocumentUrl;
+    use ProcessClassifyDocumentBase64, ProcessClassifyDocumentUrl;
 
 }
diff --git a/src/veryfi/classify/ProcessClassifyDocumentBase64.php b/src/veryfi/classify/ProcessClassifyDocumentBase64.php
new file mode 100644
index 0000000..7547279
--- /dev/null
+++ b/src/veryfi/classify/ProcessClassifyDocumentBase64.php
@@ -0,0 +1,24 @@
+<?php
+namespace veryfi\classify;
+
+trait ProcessClassifyDocumentBase64
+{
+    /**
+     * Classify a document and extract all the fields from it. https://docs.veryfi.com/api/classify/classify-a-document/
+     *
+     * @param string $base64_encoded_string Buffer string of a file to submit for classify extraction
+     * @param string $file_name The file name including the extension
+     * @param array $kwargs Additional request parameters
+     * @return string Data extracted from the document
+     */
+    public function classify_document_from_base64(string $base64_encoded_string, string $file_name, array $kwargs = []): string
+    {
+        $endpoint_name = '/classify/';
+        $request_arguments = [
+            'file_name' => $file_name,
+            'file_data' => $base64_encoded_string,
+        ];
+        $request_arguments = array_replace($request_arguments, $kwargs);
+        return $this->request('POST', $endpoint_name, $request_arguments);
+    }
+}
diff --git a/src/veryfi/classify/ProcessClassifyDocumentUrl.php b/src/veryfi/classify/ProcessClassifyDocumentUrl.php
new file mode 100644
index 0000000..a6b75d6
--- /dev/null
+++ b/src/veryfi/classify/ProcessClassifyDocumentUrl.php
@@ -0,0 +1,24 @@
+<?php
+namespace veryfi\classify;
+
+trait ProcessClassifyDocumentUrl
+{
+    /**
+     * Classify document from url and extract all the fields from it. https://docs.veryfi.com/api/classify/classify-a-document/
+     *
+     * @param string|null $file_url Required if file_urls isn't specified. Publicly accessible URL to a file.
+     * @param array|null $file_urls Required if file_url isn't specified. List of publicly accessible URLs to multiple files.
+     * @param array $kwargs Additional request parameters
+     * @return string Data extracted from the document.
+     */
+    public function classify_document_from_url(?string $file_url = null, ?array $file_urls = null, array $kwargs = []): string
+    {
+        $endpoint_name = '/classify/';
+        $request_arguments = [
+            'file_url' => $file_url,
+            'file_urls' => $file_urls
+        ];
+        $request_arguments = array_replace($request_arguments, $kwargs);
+        return $this->request('POST', $endpoint_name, $request_arguments);
+    }
+}
diff --git a/src/veryfi/client/GetHeaders.php b/src/veryfi/client/GetHeaders.php
index 2b31c28..26e9374 100644
--- a/src/veryfi/client/GetHeaders.php
+++ b/src/veryfi/client/GetHeaders.php
@@ -9,7 +9,7 @@ trait GetHeaders
     private function get_headers(): array
     {
         return array(
-            'User-Agent' => 'php veryfi-php/1.1.0',
+            'User-Agent' => 'php veryfi-php/1.0.5',
             'Accept' => 'application/json',
             'Content-Type' => 'application/json',
             'Client-ID' => $this->client_id,
diff --git a/src/veryfi/split/GetSplitDocument.php b/src/veryfi/split/GetSplitDocument.php
new file mode 100644
index 0000000..3d3db24
--- /dev/null
+++ b/src/veryfi/split/GetSplitDocument.php
@@ -0,0 +1,20 @@
+<?php
+namespace veryfi\split;
+
+trait GetSplitDocument
+{
+    /**
+     * Veryfi's Get a Documents from PDF endpoint allows you to retrieve a collection of previously processed documents. https://docs.veryfi.com/api/receipts-invoices/get-documents-from-pdf/
+     *
+     * @param string $document_id ID of the document you'd like to retrieve
+     * @param array $kwargs Additional request parameters
+     * @return string Data extracted from the Document
+     */
+    public function get_split_document(string $document_id, array $kwargs = []): string
+    {
+        $endpoint_name = "/documents-set/$document_id/";
+        $request_arguments = ['id' => $document_id];
+        $request_arguments = array_replace($request_arguments, $kwargs);
+        return $this->request('GET', $endpoint_name, $request_arguments);
+    }
+}
diff --git a/src/veryfi/split/GetSplitDocuments.php b/src/veryfi/split/GetSplitDocuments.php
new file mode 100644
index 0000000..9b16dc7
--- /dev/null
+++ b/src/veryfi/split/GetSplitDocuments.php
@@ -0,0 +1,24 @@
+<?php
+namespace veryfi\split;
+
+trait GetSplitDocuments
+{
+    /**
+     * Veryfi's Get a Submitted PDF endpoint allows you to retrieve a collection of previously processed documents. https://docs.veryfi.com/api/receipts-invoices/get-submitted-pdf/
+     *
+     * @param int $page The page number. The response is capped to maximum of 50 results per page.
+     * @param int $page_size The number of Documents per page.
+     * @param array $kwargs Additional request parameters
+     * @return string JSON object of previously processed documents
+     */
+    public function get_split_documents(int $page = 1, int $page_size = 50, array $kwargs = []): string
+    {
+        $endpoint_name = '/documents-set/';
+        $request_arguments = [
+            'page' => $page,
+            'page_size' => $page_size
+        ];
+        $request_arguments = array_replace($request_arguments, $kwargs);
+        return $this->request('GET', $endpoint_name, $request_arguments);
+    }
+}
diff --git a/src/veryfi/split/ProcessSplitDocumentBase64.php b/src/veryfi/split/ProcessSplitDocumentBase64.php
new file mode 100644
index 0000000..c375488
--- /dev/null
+++ b/src/veryfi/split/ProcessSplitDocumentBase64.php
@@ -0,0 +1,24 @@
+<?php
+namespace veryfi\split;
+
+trait ProcessSplitDocumentBase64
+{
+    /**
+     * Split document PDF from url and extract all the fields from it. https://docs.veryfi.com/api/receipts-invoices/split-and-process-a-pdf/
+     *
+     * @param string $base64_encoded_string Buffer string of a file to submit for classify extraction
+     * @param string $file_name The file name including the extension
+     * @param array $kwargs Additional request parameters
+     * @return string Data extracted from the document
+     */
+    public function split_document_from_base64(string $base64_encoded_string, string $file_name, array $kwargs = []): string
+    {
+        $endpoint_name = '/documents-set/';
+        $request_arguments = [
+            'file_name' => $file_name,
+            'file_data' => $base64_encoded_string,
+        ];
+        $request_arguments = array_replace($request_arguments, $kwargs);
+        return $this->request('POST', $endpoint_name, $request_arguments);
+    }
+}
diff --git a/src/veryfi/split/ProcessSplitDocumentUrl.php b/src/veryfi/split/ProcessSplitDocumentUrl.php
new file mode 100644
index 0000000..8a3aeca
--- /dev/null
+++ b/src/veryfi/split/ProcessSplitDocumentUrl.php
@@ -0,0 +1,24 @@
+<?php
+namespace veryfi\split;
+
+trait ProcessSplitDocumentUrl
+{
+    /**
+     * Split document PDF from url and extract all the fields from it. https://docs.veryfi.com/api/receipts-invoices/split-and-process-a-pdf/
+     *
+     * @param string|null $file_url Required if file_urls isn't specified. Publicly accessible URL to a file.
+     * @param array|null $file_urls Required if file_url isn't specified. List of publicly accessible URLs to multiple files.
+     * @param array $kwargs Additional request parameters
+     * @return string Data extracted from the document.
+     */
+    public function split_document_from_url(?string $file_url = null, ?array $file_urls = null, array $kwargs = []): string
+    {
+        $endpoint_name = '/documents-set/';
+        $request_arguments = [
+            'file_url' => $file_url,
+            'file_urls' => $file_urls
+        ];
+        $request_arguments = array_replace($request_arguments, $kwargs);
+        return $this->request('POST', $endpoint_name, $request_arguments);
+    }
+}
diff --git a/tests/ClientClassifyDocumentsTest.php b/tests/ClientClassifyDocumentsTest.php
new file mode 100644
index 0000000..1d6d3b8
--- /dev/null
+++ b/tests/ClientClassifyDocumentsTest.php
@@ -0,0 +1,59 @@
+<?php
+
+use veryfi\Client;
+
+require_once __DIR__ . '/ClientTestCase.php';
+
+class ClientClassifyDocumentsTest extends ClientTestCase
+{
+    public function test_classify_document_from_base64(): void
+    {
+        if ($this->mock_responses) {
+            $veryfi_client = $this->getMockBuilder(Client::class)
+                ->onlyMethods(['exec_curl'])
+                ->setConstructorArgs([$this->client_id, $this->client_secret, $this->username, $this->api_key])
+                ->getMock();
+
+            $file_path = __DIR__ . '/resources/processDocument.json';
+            $file = fopen($file_path, 'r');
+            $file_data = mb_convert_encoding(fread($file, filesize($file_path)), 'UTF-8');
+            $veryfi_client->expects($this->once())
+                ->method('exec_curl')
+                ->willReturn($file_data);
+
+        } else {
+            $veryfi_client = new Client($this->client_id, $this->client_secret, $this->username, $this->api_key);
+        }
+
+        $file_path = $this->receipt_path;
+        $file_name = 'receipt.jpg';
+        $base64_encoded_string = base64_encode(file_get_contents($file_path));
+
+        $json_response = json_decode($veryfi_client->classify_document_from_base64($base64_encoded_string, $file_name), true);
+        $this->assertIsArray($json_response);
+    }
+
+    public function test_classify_document_from_url(): void
+    {
+        if ($this->mock_responses) {
+            $veryfi_client = $this->getMockBuilder(Client::class)
+                ->onlyMethods(['exec_curl'])
+                ->setConstructorArgs([$this->client_id, $this->client_secret, $this->username, $this->api_key])
+                ->getMock();
+
+            $file_path = __DIR__ . '/resources/processDocument.json';
+            $file = fopen($file_path, 'r');
+            $file_data = mb_convert_encoding(fread($file, filesize($file_path)), 'UTF-8');
+            $veryfi_client->expects($this->once())
+                ->method('exec_curl')
+                ->willReturn($file_data);
+
+        } else {
+            $veryfi_client = new Client($this->client_id, $this->client_secret, $this->username, $this->api_key);
+        }
+
+        $url = 'https://raw.githubusercontent.com/veryfi/veryfi-python/master/tests/assets/receipt_public.jpg';
+        $json_response = json_decode($veryfi_client->classify_document_from_url($url), true);
+        $this->assertIsArray($json_response);
+    }
+}
diff --git a/tests/ClientSplitDocumentsTest.php b/tests/ClientSplitDocumentsTest.php
new file mode 100644
index 0000000..2da7f74
--- /dev/null
+++ b/tests/ClientSplitDocumentsTest.php
@@ -0,0 +1,111 @@
+<?php
+
+use veryfi\Client;
+
+require_once __DIR__ . '/ClientTestCase.php';
+
+class ClientSplitDocumentsTest extends ClientTestCase
+{
+    public function test_get_split_documents(): void
+    {
+        if ($this->mock_responses) {
+            $veryfi_client = $this->getMockBuilder(Client::class)
+                ->onlyMethods(['exec_curl'])
+                ->setConstructorArgs([$this->client_id, $this->client_secret, $this->username, $this->api_key])
+                ->getMock();
+
+            $file_path = __DIR__ . '/resources/getDocuments.json';
+            $file = fopen($file_path, 'r');
+            $file_data = mb_convert_encoding(fread($file, filesize($file_path)), 'UTF-8');
+            $veryfi_client->expects($this->once())
+                ->method('exec_curl')
+                ->willReturn($file_data);
+
+        } else {
+            $veryfi_client = new Client($this->client_id, $this->client_secret, $this->username, $this->api_key);
+        }
+        $json_response = json_decode($veryfi_client->get_split_documents(), true);
+        $this->assertIsArray($json_response);
+    }
+
+    public function test_get_split_document(): void
+    {
+        if ($this->mock_responses) {
+            $veryfi_client = $this->getMockBuilder(Client::class)
+                ->onlyMethods(['exec_curl'])
+                ->setConstructorArgs([$this->client_id, $this->client_secret, $this->username, $this->api_key])
+                ->getMock();
+
+            $file_path = __DIR__ . '/resources/getDocument.json';
+            $file = fopen($file_path, 'r');
+            $file_data = mb_convert_encoding(fread($file, filesize($file_path)), 'UTF-8');
+            $veryfi_client->expects($this->once())
+                ->method('exec_curl')
+                ->willReturn($file_data);
+            $document_id = '125661908';
+
+        } else {
+            $veryfi_client = new Client($this->client_id, $this->client_secret, $this->username, $this->api_key);
+            $documents = json_decode($veryfi_client->get_split_documents(), true);
+            if (isset($documents['documents'][0]['id'])) {
+                $document_id = $documents['documents'][0]['id'];
+            } else {
+                $this->markTestSkipped('No documents found to test get_split_document');
+            }
+        }
+
+        $json_response = json_decode($veryfi_client->get_split_document($document_id), true);
+        $this->assertEquals($document_id, $json_response['id']);
+    }
+
+    public function test_split_document_from_base64(): void
+    {
+        if ($this->mock_responses) {
+            $veryfi_client = $this->getMockBuilder(Client::class)
+                ->onlyMethods(['exec_curl'])
+                ->setConstructorArgs([$this->client_id, $this->client_secret, $this->username, $this->api_key])
+                ->getMock();
+
+            $file_path = __DIR__ . '/resources/processDocument.json';
+            $file = fopen($file_path, 'r');
+            $file_data = mb_convert_encoding(fread($file, filesize($file_path)), 'UTF-8');
+            $veryfi_client->expects($this->once())
+                ->method('exec_curl')
+                ->willReturn($file_data);
+
+        } else {
+            $veryfi_client = new Client($this->client_id, $this->client_secret, $this->username, $this->api_key);
+        }
+
+        $file_path = $this->receipt_path;
+        $file_name = 'receipt.jpg';
+        $base64_encoded_string = base64_encode(file_get_contents($file_path));
+
+        $json_response = json_decode($veryfi_client->split_document_from_base64($base64_encoded_string, $file_name), true);
+        $this->assertIsArray($json_response);
+    }
+
+    public function test_split_document_from_url(): void
+    {
+        if ($this->mock_responses) {
+            $veryfi_client = $this->getMockBuilder(Client::class)
+                ->onlyMethods(['exec_curl'])
+                ->setConstructorArgs([$this->client_id, $this->client_secret, $this->username, $this->api_key])
+                ->getMock();
+
+            $file_path = __DIR__ . '/resources/processDocument.json';
+            $file = fopen($file_path, 'r');
+            $file_data = mb_convert_encoding(fread($file, filesize($file_path)), 'UTF-8');
+            $veryfi_client->expects($this->once())
+                ->method('exec_curl')
+                ->willReturn($file_data);
+
+        } else {
+            $veryfi_client = new Client($this->client_id, $this->client_secret, $this->username, $this->api_key);
+        }
+
+        $url = 'https://raw.githubusercontent.com/veryfi/veryfi-python/master/tests/assets/receipt_public.jpg';
+        $json_response = json_decode($veryfi_client->split_document_from_url($url), true);
+        $this->assertIsArray($json_response);
+    }
+}