PHP如何調用Asciidoctor轉換 Asciidoctor調用教程快速轉換文檔格式

449

php調用asciidoctor的核心在于通過exec()或shell_exec()函數執行asciidoctor命令，實現將asciidoc文檔轉換為html等格式。1. 確保環境正確配置：安裝asciidoctor和ruby環境，并確認asciidoctor路徑；2. php代碼中使用escapeshellcmd()和exec()執行轉換命令，并處理返回值以判斷執行是否成功；3. 注意權限問題，確保php進程有執行asciidoctor及讀寫相關文件的權限；4. 處理中文路徑或文件名時，使用escapeshellarg()并設置正確的字符編碼與locale；5. 使用絕對路徑、避免特殊字符，并合理配置asciidoctor選項如doctype、backend、stylesheet等；6. 可通過-gem安裝擴展（如asciidoctor-diagram）并在命令中加載以支持額外功能；7. 調試時應檢查asciidoctor是否安裝正確、exec()是否被禁用以及asciidoc文檔是否存在語法錯誤。整個過程需關注安全性、兼容性與錯誤日志記錄，以保障轉換順利進行。

PHP如何調用Asciidoctor轉換 Asciidoctor調用教程快速轉換文檔格式

PHP調用Asciidoctor，本質上就是讓php腳本能夠執行Asciidoctor的命令，從而將Asciidoc格式的文檔轉換成HTML或其他格式。關鍵在于正確配置環境，并使用exec()或shell_exec()這類函數來調用Asciidoctor。

PHP如何調用Asciidoctor轉換 Asciidoctor調用教程快速轉換文檔格式

解決方案

PHP如何調用Asciidoctor轉換 Asciidoctor調用教程快速轉換文檔格式

  1. 環境準備：

    立即學習“PHP免費學習筆記（深入）”；

    • 安裝Asciidoctor： 確保服務器上已經安裝了Asciidoctor。如果服務器是linux環境，可以通過包管理器安裝（例如sudo apt-get install asciidoctor或sudo yum install asciidoctor）。如果是其他環境，需要按照Asciidoctor官方文檔進行安裝。
    • Ruby環境： Asciidoctor是用Ruby編寫的，所以需要安裝Ruby環境。同樣，根據服務器的操作系統選擇合適的安裝方式。
    • 確認路徑： 找到Asciidoctor可執行文件的路徑。通常在/usr/bin/asciidoctor或/usr/local/bin/asciidoctor。可以使用which asciidoctor命令來查找。

  2. PHP代碼：

    PHP如何調用Asciidoctor轉換 Asciidoctor調用教程快速轉換文檔格式

    <?php  function convertAsciidocToHtml(string $asciidocFilePath, string $outputFilePath): bool {     $asciidoctorPath = '/usr/bin/asciidoctor'; // 替換為你的Asciidoctor可執行文件路徑     $command = escapeshellcmd("$asciidoctorPath -o $outputFilePath $asciidocFilePath");      // 記錄命令，方便調試     error_log("Executing command: " . $command);      $output = [];     $returnCode = 0;     exec($command, $output, $returnCode);      // 記錄輸出，方便調試     error_log("Command output: " . implode("n", $output));     error_log("Return code: " . $returnCode);      if ($returnCode !== 0) {         error_log("Asciidoctor conversion failed with return code: " . $returnCode);         return false;     }      return true; }  // 示例用法 $asciidocFile = '/path/to/your/document.adoc'; // 替換為你的Asciidoc文件路徑 $htmlFile = '/path/to/your/output.html';   // 替換為輸出HTML文件的路徑  if (convertAsciidocToHtml($asciidocFile, $htmlFile)) {     echo "Asciidoc file converted successfully to HTML!"; } else {     echo "Asciidoc file conversion failed."; }  ?>
    • escapeshellcmd()函數： 這個函數非常重要，它可以確保傳遞給shell的參數是安全的，防止命令注入攻擊。
    • exec()函數： exec()函數執行一個外部程序。它接受三個參數：要執行的命令、輸出數組（命令的輸出會被寫入這個數組）和返回代碼（命令的退出狀態）。
    • 錯誤處理： 代碼中包含了簡單的錯誤處理機制，檢查exec()函數的返回代碼，如果返回代碼不是0，表示命令執行失敗。同時，使用error_log()記錄命令和輸出，方便調試。

  3. 權限問題：

    • 確保PHP進程有執行Asciidoctor可執行文件的權限。通常，Web服務器運行PHP腳本的用戶（例如www-data或apache）需要有執行Asciidoctor的權限。可以通過chmod +x /usr/bin/asciidoctor命令來賦予執行權限。
    • 確保PHP進程有讀寫Asciidoc文件和輸出HTML文件的權限。

  4. 其他方法：

    • shell_exec()函數： shell_exec()函數也可以用來執行外部程序，它返回命令的完整輸出，而不是像exec()那樣將輸出寫入數組。可以使用$output = shell_exec($command);來獲取輸出。
    • symfony Process組件： 如果項目使用了Symfony框架，可以使用Symfony Process組件來執行外部程序。Process組件提供了更高級的功能，例如設置超時時間、設置環境變量等。

Asciidoctor轉換失敗的常見原因及排查方法

Asciidoctor轉換失敗的原因有很多，不僅僅是PHP代碼的問題，還可能涉及到環境配置、文件權限、Asciidoc文檔本身的問題。

  1. Asciidoctor未正確安裝或路徑錯誤：

    • 排查方法： 首先，確認Asciidoctor是否已經正確安裝。在終端中執行asciidoctor –version命令，如果能夠顯示Asciidoctor的版本信息，說明安裝成功。然后，確認PHP代碼中的$asciidoctorPath變量是否指向正確的Asciidoctor可執行文件路徑。可以使用which asciidoctor命令來查找Asciidoctor的路徑。

  2. PHP進程沒有執行Asciidoctor的權限：

    • 排查方法： Web服務器運行PHP腳本的用戶（例如www-data或apache）需要有執行Asciidoctor的權限。可以通過以下步驟來檢查和修改權限：
      1. 找到Web服務器運行PHP腳本的用戶。可以通過ps aux | grep httpd或ps aux | grep apache命令來查找。
      2. 使用ls -l /usr/bin/asciidoctor命令來查看Asciidoctor可執行文件的權限。
      3. 如果Web服務器運行PHP腳本的用戶沒有執行權限，可以使用chmod +x /usr/bin/asciidoctor命令來賦予執行權限。如果需要更精細的權限控制，可以使用chown命令來修改Asciidoctor的所有者或所屬組。

  3. PHP進程沒有讀寫Asciidoc文件和輸出HTML文件的權限：

    • 排查方法： 同樣，需要確保Web服務器運行PHP腳本的用戶有讀寫Asciidoc文件和輸出HTML文件的權限。可以使用ls -l /path/to/your/document.adoc和ls -l /path/to/your/output.html命令來查看文件權限。如果權限不足，可以使用chmod命令來修改權限，或者使用chown命令來修改文件所有者或所屬組。

  4. Asciidoc文檔本身存在語法錯誤：

    • 排查方法： Asciidoc文檔的語法錯誤會導致Asciidoctor轉換失敗。可以使用Asciidoctor命令行工具來驗證Asciidoc文檔的語法：asciidoctor -v /path/to/your/document.adoc。如果存在語法錯誤，Asciidoctor會輸出錯誤信息。根據錯誤信息修改Asciidoc文檔。

  5. PHP的exec()函數被禁用：

    • 排查方法： 有些服務器配置會禁用PHP的exec()函數，以防止安全風險。可以通過phpinfo()函數來查看exec()函數是否被禁用。如果被禁用，需要修改PHP配置文件（php.ini），移除disable_functions配置中的exec。注意： 禁用exec()函數是一種安全措施，解除禁用可能會帶來安全風險，請謹慎操作。

  6. escapeshellcmd()函數轉義不正確：

    • 排查方法： 雖然escapeshellcmd()函數可以防止命令注入攻擊，但如果使用不當，可能會導致Asciidoctor命令無法正確執行。例如，如果Asciidoc文件路徑或輸出HTML文件路徑包含空格或特殊字符，escapeshellcmd()函數可能會轉義這些字符，導致Asciidoctor無法找到文件。可以嘗試手動構建Asciidoctor命令，并使用var_dump()函數來查看命令是否正確。

  7. Asciidoctor擴展或主題缺失：

    • 排查方法： Asciidoctor支持擴展和主題，可以擴展Asciidoctor的功能或改變輸出HTML的樣式。如果Asciidoc文檔使用了某個擴展或主題，但服務器上沒有安裝該擴展或主題，Asciidoctor轉換會失敗。需要安裝相應的擴展或主題。

PHP調用Asciidoctor時如何處理中文文件名或路徑

處理中文文件名或路徑的關鍵在于確保字符編碼的一致性，并正確處理轉義。

  1. 確保文件編碼一致：

    • Asciidoc文件、PHP腳本以及Web服務器的字符編碼應該保持一致，通常推薦使用UTF-8編碼。可以使用文本編輯器將Asciidoc文件保存為UTF-8編碼。可以在PHP腳本中使用header(‘Content-Type: text/html; charset=utf-8’);來設置HTTP響應的字符編碼。

  2. 使用escapeshellarg()函數：

    • escapeshellarg()函數比escapeshellcmd()函數更適合處理包含空格或特殊字符的文件名或路徑。escapeshellarg()函數會將參數用單引號括起來，并轉義單引號本身，從而確保參數被正確傳遞給shell。
    <?php  function convertAsciidocToHtml(string $asciidocFilePath, string $outputFilePath): bool {     $asciidoctorPath = '/usr/bin/asciidoctor';     $command = escapeshellcmd("$asciidoctorPath -o " . escapeshellarg($outputFilePath) . " " . escapeshellarg($asciidocFilePath));      $output = [];     $returnCode = 0;     exec($command, $output, $returnCode);      if ($returnCode !== 0) {         return false;     }      return true; }  $asciidocFile = '/path/to/你的文檔.adoc'; // 中文文件名 $htmlFile = '/path/to/輸出目錄/你的文檔.html'; // 中文路徑  if (convertAsciidocToHtml($asciidocFile, $htmlFile)) {     echo "Asciidoc file converted successfully to HTML!"; } else {     echo "Asciidoc file conversion failed."; }  ?>

  3. 檢查PHP的locale設置：

    • PHP的locale設置會影響字符串處理。可以使用setlocale()函數來設置locale。
    <?php  setlocale(LC_ALL, 'zh_CN.UTF-8'); // 設置locale為中文UTF-8  function convertAsciidocToHtml(string $asciidocFilePath, string $outputFilePath): bool {     $asciidoctorPath = '/usr/bin/asciidoctor';     $command = escapeshellcmd("$asciidoctorPath -o " . escapeshellarg($outputFilePath) . " " . escapeshellarg($asciidocFilePath));      $output = [];     $returnCode = 0;     exec($command, $output, $returnCode);      if ($returnCode !== 0) {         return false;     }      return true; }  $asciidocFile = '/path/to/你的文檔.adoc'; // 中文文件名 $htmlFile = '/path/to/輸出目錄/你的文檔.html'; // 中文路徑  if (convertAsciidocToHtml($asciidocFile, $htmlFile)) {     echo "Asciidoc file converted successfully to HTML!"; } else {     echo "Asciidoc file conversion failed."; }  ?>

  4. 使用絕對路徑：

    • 盡量使用絕對路徑來指定Asciidoc文件和輸出HTML文件的路徑，避免相對路徑帶來的問題。

  5. 避免在文件名或路徑中使用特殊字符：

    • 雖然可以使用escapeshellarg()函數來處理包含空格或特殊字符的文件名或路徑，但最好還是避免在文件名或路徑中使用特殊字符，以減少出錯的可能性。

Asciidoctor的常用選項和配置

Asciidoctor提供了豐富的選項和配置，可以控制轉換過程的各個方面，例如輸出格式、樣式、標題、屬性等。

  1. 常用選項：

    • -o 或 –output ：指定輸出文件。
    • -d 或 –doctype ：指定文檔類型。常用的文檔類型有article、book、manpage。
    • -b 或 –backend ：指定后端。常用的后端有html5、docbook5。
    • -a = 或 –Attribute =：設置屬性。可以使用屬性來控制文檔的各個方面，例如標題、作者、版本等。
    • -s 或 –standalone：生成獨立的HTML文件，包含所有的css和JavaScript。
    • -n 或 –no-header-footer：不生成HTML的頭部和尾部。
    • -r 或 –require ：加載Ruby庫。
    • -v 或 –verbose：顯示詳細的輸出信息。
    • -q 或 –quiet：不顯示任何輸出信息。

  2. 配置文件：

    • Asciidoctor可以使用配置文件來指定默認選項和屬性。配置文件通常命名為asciidoctor.conf或.asciidoctorconfig，位于當前目錄或用戶主目錄下。
    • 配置文件可以使用Ruby語法。
    # asciidoctor.conf  # 設置默認后端為html5 :backend: html5  # 設置文檔類型為article :doctype: article  # 設置屬性 :author: Your Name :email: your.email@example.com :revnumber: 1.0

  3. 在PHP代碼中傳遞選項：

    • 可以通過在PHP代碼中構建Asciidoctor命令時傳遞選項。
    <?php  function convertAsciidocToHtml(string $asciidocFilePath, string $outputFilePath, array $options = []): bool {     $asciidoctorPath = '/usr/bin/asciidoctor';     $command = escapeshellcmd($asciidoctorPath);      // 添加選項     foreach ($options as $option => $value) {         $command .= ' ' . escapeshellarg($option . '=' . $value);     }      $command .= ' -o ' . escapeshellarg($outputFilePath) . ' ' . escapeshellarg($asciidocFilePath);      $output = [];     $returnCode = 0;     exec($command, $output, $returnCode);      if ($returnCode !== 0) {         return false;     }      return true; }  $asciidocFile = '/path/to/your/document.adoc'; $htmlFile = '/path/to/your/output.html';  // 設置選項 $options = [     'doctype' => 'article',     'backend' => 'html5',     'attribute' => 'author=Your Name' ];  if (convertAsciidocToHtml($asciidocFile, $htmlFile, $options)) {     echo "Asciidoc file converted successfully to HTML!"; } else {     echo "Asciidoc file conversion failed."; }  ?>

  4. 常用屬性：

    • doctype：文檔類型。
    • backend：后端。
    • title：文檔標題。
    • author：作者。
    • email：作者郵箱。
    • revnumber：版本號。
    • revdate：發布日期。
    • stylesheet：CSS樣式表。
    • icons：圖標。
    • toc：目錄。

如何使用Asciidoctor的擴展和主題

Asciidoctor的擴展和主題可以擴展Asciidoctor的功能，改變輸出HTML的樣式。

  1. 擴展：

    • Asciidoctor的擴展是用Ruby編寫的，可以擴展Asciidoctor的語法、轉換過程、輸出格式等。

    • 常用的擴展有：

      • asciidoctor-diagram：支持在Asciidoc文檔中嵌入uml圖、流程圖等。
      • asciidoctor-plantuml：支持在Asciidoc文檔中嵌入PlantUML圖。
      • asciidoctor-rouge：使用Rouge語法高亮器來高亮代碼。

    • 安裝擴展：

      gem install asciidoctor-diagram gem install asciidoctor-plantuml gem install asciidoctor-rouge

    • 在Asciidoc文檔中使用擴展：

      [plantuml,format=png] .... @startuml Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response Alice -> Bob: Another authentication Request Alice <-- Bob: Another authentication Response @enduml ....

    • 在PHP代碼中加載擴展：

      <?php  function convertAsciidocToHtml(string $asciidocFilePath, string $outputFilePath): bool {     $asciidoctorPath = '/usr/bin/asciidoctor';     $command = escapeshellcmd("$asciidoctorPath -r asciidoctor-diagram -o $outputFilePath $asciidocFilePath");      $output = [];     $returnCode = 0;     exec($command, $output, $returnCode);      if ($returnCode !== 0) {         return false;     }      return true; }  $asciidocFile = '/path/to/your/document.adoc'; $htmlFile = '/path/to/your/output.html';  if (convertAsciidocToHtml($asciidocFile, $htmlFile)) {     echo "Asciidoc file converted successfully to HTML!"; } else {     echo "Asciidoc file conversion failed."; }  ?>

  2. 主題：

    • Asciidoctor的主題定義了輸出HTML的樣式。

    • Asciidoctor默認使用default主題。

    • 可以使用自定義CSS樣式表來覆蓋默認主題的樣式。

    • 可以使用第三方主題，例如asciidoctor-skins。

    • 安裝主題：

      gem install asciidoctor-skins

    • 在Asciidoc文檔中使用主題：

      :stylesheet: path/to/your/custom.css

    • 在PHP代碼中指定主題：

      <?php  function convertAsciidocToHtml(string $asciidocFilePath, string $outputFilePath): bool {     $asciidoctorPath = '/usr/bin/asciidoctor';     $command = escapeshellcmd("$asciidoctorPath -a stylesheet=path/to/your/custom.css -o $outputFilePath $asciidocFilePath");      $output = [];     $returnCode = 0;     exec($command, $output, $returnCode);      if ($returnCode !== 0) {         return false;     }      return true; }  $asciidocFile = '/path/to/your/document.adoc'; $htmlFile = '/path/to/your/output.html';  if (convertAsciidocToHtml($asciidocFile, $htmlFile)) {     echo "Asciidoc file converted successfully to HTML!"; } else {     echo "Asciidoc file conversion failed."; }  ?>

總的來說，PHP調用Asciidoctor進行文檔轉換需要關注環境配置、權限問題、參數傳遞、錯誤處理等方面。 掌握這些要點，就能順利地將Asciidoc文檔轉換為各種格式，并集成到PHP項目中。

? 版權聲明
THE END
后端開發
# linux# 工具# php# ai# http# 字符串# html# JavaScript# 操作系統# css# apache# default# require# 郵箱# symfony# html5# 樣式表# ruby# php腳本# Attribute# uml
喜歡就支持一下吧
點贊9 分享