什麼是mysqli_stmt::send_long_data 函數？它的基礎用法和注意事項有哪些？

gitbox 2025-08-28

什麼是mysqli_stmt::send_long_data 函數？它的基礎用法和注意事項有哪些？

在PHP 的MySQLi 擴展中， mysqli_stmt::send_long_data是一個用於發送大數據（如大文本、大二進制數據等）到MySQL 數據庫的函數。當處理大規模的數據插入時，常規的bind_param()方法可能會受到數據大小限制，這時候send_long_data()就顯得尤為重要。本文將介紹mysqli_stmt::send_long_data的基本用法以及使用時的注意事項。

一、函數原型

<span><span>mysqli_stmt::</span><span><span class="hljs-title function_ invoke__">send_long_data</span></span><span>(</span><span><span class="hljs-keyword">int</span></span><span> </span><span><span class="hljs-variable">$param_nr</span></span><span>, </span><span><span class="hljs-keyword">string</span></span><span> </span><span><span class="hljs-variable">$data</span></span><span>): </span><span><span class="hljs-keyword">bool</span></span><span>
</span></span>

$param_nr ：表示要發送的數據的參數編號。它對應於SQL 語句中?佔位符的位置，從0 開始計數。
$data ：表示要發送的大數據，通常是一個大字符串或二進制數據。

返回值：成功時返回true ，失敗時返回false 。

二、 send_long_data的使用場景

send_long_data主要用於將大量數據傳輸到MySQL 數據庫中。通常情況下， mysqli_stmt::bind_param()用於綁定參數，但是如果數據量較大（例如，大文件的內容、大文本字段等），則會受到PHP 配置文件中max_allowed_packet的限制。為了避免這種限制，可以使用send_long_data方法將數據分塊發送到MySQL 數據庫。

三、基礎用法

假設我們有一個表格，結構如下：

 <span><span><span class="hljs-keyword">CREATE</span></span><span> </span><span><span class="hljs-keyword">TABLE</span></span><span> files (
    id </span><span><span class="hljs-type">INT</span></span><span> AUTO_INCREMENT </span><span><span class="hljs-keyword">PRIMARY</span></span><span> KEY,
    name </span><span><span class="hljs-type">VARCHAR</span></span><span>(</span><span><span class="hljs-number">255</span></span><span>),
    file_data LONGBLOB
);
</span></span>

在這個表中，我們存儲文件的名稱以及對應的文件二進制數據。我們通過以下步驟來插入大文件數據。

 <span><span><span class="hljs-meta">&lt;?php</span></span><span>
</span><span><span class="hljs-comment">// 創建數據庫連接</span></span><span>
</span><span><span class="hljs-variable">$mysqli</span></span><span> = </span><span><span class="hljs-keyword">new</span></span><span> </span><span><span class="hljs-title function_ invoke__">mysqli</span></span><span>(</span><span><span class="hljs-string">"localhost"</span></span><span>, </span><span><span class="hljs-string">"username"</span></span><span>, </span><span><span class="hljs-string">"password"</span></span><span>, </span><span><span class="hljs-string">"database"</span></span><span>);

</span><span><span class="hljs-comment">// 檢查連接</span></span><span>
</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$mysqli</span></span><span>-&gt;connect_error) {
    </span><span><span class="hljs-keyword">die</span></span><span>(</span><span><span class="hljs-string">"連接失敗: "</span></span><span> . </span><span><span class="hljs-variable">$mysqli</span></span><span>-&gt;connect_error);
}

</span><span><span class="hljs-comment">// 準備 SQL 語句</span></span><span>
</span><span><span class="hljs-variable">$stmt</span></span><span> = </span><span><span class="hljs-variable">$mysqli</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">prepare</span></span><span>(</span><span><span class="hljs-string">"INSERT INTO files (name, file_data) VALUES (?, ?)"</span></span><span>);

</span><span><span class="hljs-comment">// 綁定第一個參數（文件名）</span></span><span>
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">bind_param</span></span><span>(</span><span><span class="hljs-string">"s"</span></span><span>, </span><span><span class="hljs-variable">$name</span></span><span>);

</span><span><span class="hljs-comment">// 讀取文件數據</span></span><span>
</span><span><span class="hljs-variable">$filePath</span></span><span> = </span><span><span class="hljs-string">'large_file.txt'</span></span><span>;
</span><span><span class="hljs-variable">$fileData</span></span><span> = </span><span><span class="hljs-title function_ invoke__">file_get_contents</span></span><span>(</span><span><span class="hljs-variable">$filePath</span></span><span>);

</span><span><span class="hljs-comment">// 發送大數據</span></span><span>
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">send_long_data</span></span><span>(</span><span><span class="hljs-number">1</span></span><span>, </span><span><span class="hljs-variable">$fileData</span></span><span>);

</span><span><span class="hljs-comment">// 設置文件名</span></span><span>
</span><span><span class="hljs-variable">$name</span></span><span> = </span><span><span class="hljs-title function_ invoke__">basename</span></span><span>(</span><span><span class="hljs-variable">$filePath</span></span><span>);

</span><span><span class="hljs-comment">// 執行 SQL 語句</span></span><span>
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">execute</span></span><span>();

</span><span><span class="hljs-comment">// 關閉連接</span></span><span>
</span><span><span class="hljs-variable">$stmt</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">close</span></span><span>();
</span><span><span class="hljs-variable">$mysqli</span></span><span>-&gt;</span><span><span class="hljs-title function_ invoke__">close</span></span><span>();
</span><span><span class="hljs-meta">?&gt;</span></span><span>
</span></span>

在上面的代碼中，我們通過bind_param()方法綁定了文件名（ s表示字符串類型）。文件數據是通過send_long_data()方法發送的，這樣就可以傳輸大文件數據。

四、 send_long_data的工作機制

分塊發送數據： send_long_data會將數據分塊發送到MySQL，而不會像傳統的bind_param()一樣一次性將數據全部綁定。當數據較大時，使用send_long_data可以避免內存佔用過高和PHP 的執行時間限制。
支持大數據類型： send_long_data主要用於LONGBLOB、LONGTEXT 類型的數據傳輸，尤其是在上傳或插入大文件時。
參數編號： send_long_data使用參數編號來標識要發送的數據塊。編號從0 開始計數，所以在多次調用send_long_data時，需確保正確的參數編號。

五、注意事項

MySQL 配置限制：在使用send_long_data時，需要注意MySQL 配置中的max_allowed_packet參數的大小。如果傳輸的數據超過此限制，插入會失敗。可以通過以下SQL 語句檢查當前配置：

 <span><span><span class="hljs-keyword">SHOW</span></span><span> VARIABLES </span><span><span class="hljs-keyword">LIKE</span></span><span> </span><span><span class="hljs-string">'max_allowed_packet'</span></span><span>;
</span></span>

若需要更改該值，可以在MySQL 配置文件中修改：

 <span><span><span class="hljs-attr">max_allowed_packet</span></span><span>=</span><span><span class="hljs-number">64</span></span><span>M
</span></span>

PHP 配置限制：此外，PHP 配置文件中的upload_max_filesize和post_max_size參數也可能會限製文件上傳的大小。在使用send_long_data時，確保這些配置足夠大。
數據庫連接的超時設置：由於send_long_data會分塊傳輸大數據，因此長時間的數據庫操作可能導致連接超時。可以通過調整MySQL 或PHP 的超時設置來避免這種情況。
數據傳輸的順序： send_long_data的調用順序與綁定參數的順序相一致。在多次調用時，確保每次發送的數據對應正確的參數編號。

六、總結

mysqli_stmt::send_long_data是一個非常實用的函數，尤其是在需要插入大文件或大數據時，它能夠有效解決傳統參數綁定方法的局限性。通過合理使用該函數，可以確保大數據的順利插入，同時避免內存不足或傳輸超時的問題。然而，使用時也需要注意MySQL 和PHP 的相關配置，確保數據傳輸不受限制。