[DRAFT] ✨ swap out all PDF/Image handling capabilities with Bernard L'Édit

.github/workflows/_build-bernard-ledit.yml

@@ -0,0 +1,115 @@
+#
+# Build the bernard_ledit PHP extension from the submodule.
+#
+name: Build bernard-ledit PHP extension
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-extension:
+    name: Build bernard-ledit for PHP ${{ matrix.php-version }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        php-version:
+          - 8.1
+          - 8.2
+          - 8.3
+          - 8.4
+          - 8.5
+    # Built on the oldest supported glibc, runs on ubuntu-latest.
+    runs-on: "ubuntu-22.04"
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      - name: Resolve bernard-ledit submodule commit
+        id: bernard
+        run: echo "sha=$(git -C bernard-ledit rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      # Skip the whole Rust build when the submodule pointer is unchanged.
+      # The extension is tied to the PHP minor version it was built against, hence the PHP version in the key.
+      - name: Restore cached bernard-ledit build
+        id: cache
+        uses: actions/cache@v5
+        with:
+          path: ./.github/artifacts/bernard-ledit
+          key: bernard-ledit-php-${{ matrix.php-version }}-${{ runner.os }}-${{ steps.bernard.outputs.sha }}
+
+      # Must run before cargo: ext-php-rs builds against the php-config found in PATH.
+      - name: Set up PHP ${{ matrix.php-version }}
+        if: steps.cache.outputs.cache-hit != 'true'
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+
+      # The runner ships several LLVMs: clang-sys loads the newest libclang, while bindgen adds the
+      # include paths of the default `clang` (14). Mixing them breaks parsing of Clang 14's SSE headers,
+      # so pin libclang to the same version as the default clang.
+      - name: Install libclang
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libclang-14-dev
+          echo "LIBCLANG_PATH=/usr/lib/llvm-14/lib" >> "$GITHUB_ENV"
+
+      - name: Set up Rust toolchain
+        if: steps.cache.outputs.cache-hit != 'true'
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache downloaded PDFium binary
+        if: steps.cache.outputs.cache-hit != 'true'
+        uses: actions/cache@v5
+        with:
+          path: bernard-ledit/core/.pdfium_cache
+          key: pdfium-${{ runner.os }}-${{ hashFiles('bernard-ledit/core/build.rs') }}
+          restore-keys: |
+            pdfium-${{ runner.os }}-
+
+      - name: Cache Rust build
+        if: steps.cache.outputs.cache-hit != 'true'
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: bernard-ledit
+          key: php-${{ matrix.php-version }}-${{ steps.bernard.outputs.sha }}
+
+      - name: Build bernard-ledit PHP extension
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          cargo build -p bernard-ledit-php --release --manifest-path bernard-ledit/Cargo.toml
+          mkdir -p ./.github/artifacts/bernard-ledit
+          cp bernard-ledit/target/release/libbernard_ledit_php.so ./.github/artifacts/bernard-ledit/bernard_ledit.so
+
+      # The extension is linked dynamically against PDFium; ship the library so consumers can set bernard_ledit.pdfium_path.
+      - name: Collect bundled PDFium library
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          lib=$(find bernard-ledit/core/.pdfium_cache -name 'libpdfium.so' -print | head -n 1)
+          if [ -z "$lib" ]; then
+            echo "::error::PDFium library not found under bernard-ledit/core/.pdfium_cache after build"
+            exit 1
+          fi
+          cp "$lib" ./.github/artifacts/bernard-ledit/
+
+      - name: Check the extension loads
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          php -d extension="$PWD/.github/artifacts/bernard-ledit/bernard_ledit.so" \
+              -d bernard_ledit.pdfium_path="$PWD/.github/artifacts/bernard-ledit/libpdfium.so" \
+              -r 'exit(extension_loaded("bernard_ledit") && 0 === BernardLedit\Pdf\PdfDocument::create()->pageCount() ? 0 : 1);'
+
+      - name: Upload bernard-ledit build
+        uses: actions/upload-artifact@v4
+        with:
+          name: bernard-ledit-php-${{ matrix.php-version }}
+          path: |
+            ./.github/artifacts/bernard-ledit/bernard_ledit.so
+            ./.github/artifacts/bernard-ledit/libpdfium.so
+          if-no-files-found: error

.github/workflows/_static-analysis.yml

@@ -9,6 +9,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v6
+      with:
+        submodules: recursive
 
     - name: Set up PHP
       uses: shivammathur/setup-php@v2

.github/workflows/_test-integrations.yml

@@ -38,32 +38,35 @@ jobs:
       - uses: actions/checkout@v6
         with:
           submodules: recursive
-      - name: Install Ghostscript
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y ghostscript
+
+      # Built by _build-bernard-ledit.yml, which the calling workflow must run first.
+      - name: Download bernard-ledit PHP extension
+        uses: actions/download-artifact@v4
+        with:
+          name: bernard-ledit-php-${{ matrix.php-version }}
+          path: ${{ github.workspace }}/.github/artifacts/bernard-ledit
 
       - name: Set up PHP ${{ matrix.php-version }}
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
-          extensions: curl, fileinfo, json, imagick
+          extensions: curl, fileinfo, json
+          ini-values: >-
+            extension=${{ github.workspace }}/.github/artifacts/bernard-ledit/bernard_ledit.so,
+            bernard_ledit.pdfium_path=${{ github.workspace }}/.github/artifacts/bernard-ledit/libpdfium.so
+
+      - name: Check bernard-ledit is loaded
+        run: |
+          php -r 'exit(extension_loaded("bernard_ledit") ? 0 : 1);'
 
       - name: Install dependencies
         uses: ramsey/composer-install@v3
 
-      - name: Change ImageMagick security policy on Ubuntu
-        run: |
-          DQT='"'
-          SRC="rights=${DQT}none${DQT} pattern=${DQT}PDF${DQT}"
-          RPL="rights=${DQT}read|write${DQT} pattern=${DQT}PDF${DQT}"
-          sudo sed -i "s/$SRC/$RPL/" /etc/ImageMagick-6/policy.xml
-
       - name: Unit testing with phpunit
         run: |
           ./vendor/bin/phpunit -c tests/functional.xml
 
-# MacOS testing disabled because of capricious GS/ImageMagick/Homebrew behaviors
+# MacOS testing disabled until bernard-ledit is built for macOS.
 #  integration-tests-macos:
 #    name: Run Integration Tests on MacOS
 #    timeout-minutes: 30
@@ -109,23 +112,18 @@ jobs:
       - uses: actions/checkout@v6
         with:
           submodules: recursive
-      - name: Install Ghostscript
-        run: choco install ghostscript --version 10.03.1 -y
-
       - name: Set up PHP ${{ matrix.php-version }}
         uses: shivammathur/setup-php@v2
         env:
           phpts: zts
         with:
           php-version: ${{ matrix.php-version }}
-          extensions: curl, fileinfo, json, imagick
-
-      - name: Install Ghostscript
-        run: choco install ghostscript -y
+          extensions: curl, fileinfo, json
 
       - name: Install dependencies
         uses: ramsey/composer-install@v3
 
+      # bernard-ledit isn't built for Windows yet: skip the tests that need it.
       - name: Unit testing with phpunit
         run: |
-          ./vendor/bin/phpunit -c tests/functional.xml
+          ./vendor/bin/phpunit -c tests/functional.xml --exclude-group bernard-ledit

.github/workflows/_test-units.yml

@@ -46,30 +46,35 @@ jobs:
           - 8.2
           - 8.3
           - 8.4
+          - 8.5
     runs-on: "ubuntu-latest"
     steps:
       - uses: actions/checkout@v6
         with:
           submodules: recursive
-      - name: Install Ghostscript
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y ghostscript
+
+      # Built by _build-bernard-ledit.yml, which the calling workflow must run first.
+      - name: Download bernard-ledit PHP extension
+        uses: actions/download-artifact@v4
+        with:
+          name: bernard-ledit-php-${{ matrix.php-version }}
+          path: ${{ github.workspace }}/.github/artifacts/bernard-ledit
+
       - name: Set up PHP ${{ matrix.php-version }}
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
+          ini-values: >-
+            extension=${{ github.workspace }}/.github/artifacts/bernard-ledit/bernard_ledit.so,
+            bernard_ledit.pdfium_path=${{ github.workspace }}/.github/artifacts/bernard-ledit/libpdfium.so
+
+      - name: Check bernard-ledit is loaded
+        run: |
+          php -r 'exit(extension_loaded("bernard_ledit") ? 0 : 1);'
 
       - name: Install dependencies
         uses: ramsey/composer-install@v3
 
-      - name: Change ImageMagick security policy on Ubuntu
-        run: |
-          DQT='"'
-          SRC="rights=${DQT}none${DQT} pattern=${DQT}PDF${DQT}"
-          RPL="rights=${DQT}read|write${DQT} pattern=${DQT}PDF${DQT}"
-          sudo sed -i "s/$SRC/$RPL/" /etc/ImageMagick-6/policy.xml
-
       - name: Unit testing with phpunit
         env:
           MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
@@ -105,7 +110,7 @@ jobs:
         run: |
           ./vendor/bin/phpunit -c tests/pdffeatures.xml
 
-# Note: Disabled because brew formula for imagemagick keeps breaking
+# Note: Disabled until bernard-ledit is built for macOS (see bernard-ledit HANDOVER).
 #  with-pdf-macos:
 #    name: Unit Tests on MacOS with PDF support
 #    timeout-minutes: 30
@@ -181,43 +186,44 @@ jobs:
           ./vendor/bin/phpunit -c tests/pdffeatures.xml
 
 
-  with-pdf-windows:
-    name: Unit Tests on Windows with PDF support
-    timeout-minutes: 30
-    strategy:
-      matrix:
-        php-version:
-          - 8.1
-          - 8.2
-          - 8.3
-          - 8.4
-    runs-on: "windows-latest"
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          submodules: recursive
-      - name: Install Ghostscript
-        run: choco install ghostscript --version 10.04.0 -y
-
-      - name: Create Ghostscript alias
-        run: |
-          New-Item -ItemType SymbolicLink -Path "C:\Windows\gs.exe" -Target "C:\Program Files\gs\gs10.04.0\bin\gswin64c.exe"
-          New-Item -ItemType SymbolicLink -Path "C:\Windows\gs" -Target "C:\Program Files\gs\gs10.04.0\bin\gswin64c.exe"
-        shell: powershell
-
-      - name: Set up PHP ${{ matrix.php-version }}
-        uses: shivammathur/setup-php@v2
-        env:
-          phpts: zts
-        with:
-          php-version: ${{ matrix.php-version }}
-          extensions: curl, fileinfo, json, imagick
-
-      - name: Install dependencies
-        uses: ramsey/composer-install@v3
-
-      - name: Unit testing with phpunit
-        env:
-          MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
-        run: |
-          ./vendor/bin/phpunit -c tests/phpunit.xml
+# Note: Disabled until bernard-ledit is built for Windows (needs nightly Rust, see bernard-ledit HANDOVER).
+#  with-pdf-windows:
+#    name: Unit Tests on Windows with PDF support
+#    timeout-minutes: 30
+#    strategy:
+#      matrix:
+#        php-version:
+#          - 8.1
+#          - 8.2
+#          - 8.3
+#          - 8.4
+#    runs-on: "windows-latest"
+#    steps:
+#      - uses: actions/checkout@v6
+#        with:
+#          submodules: recursive
+#      - name: Install Ghostscript
+#        run: choco install ghostscript --version 10.04.0 -y
+#
+#      - name: Create Ghostscript alias
+#        run: |
+#          New-Item -ItemType SymbolicLink -Path "C:\Windows\gs.exe" -Target "C:\Program Files\gs\gs10.04.0\bin\gswin64c.exe"
+#          New-Item -ItemType SymbolicLink -Path "C:\Windows\gs" -Target "C:\Program Files\gs\gs10.04.0\bin\gswin64c.exe"
+#        shell: powershell
+#
+#      - name: Set up PHP ${{ matrix.php-version }}
+#        uses: shivammathur/setup-php@v2
+#        env:
+#          phpts: zts
+#        with:
+#          php-version: ${{ matrix.php-version }}
+#          extensions: curl, fileinfo, json, imagick
+#
+#      - name: Install dependencies
+#        uses: ramsey/composer-install@v3
+#
+#      - name: Unit testing with phpunit
+#        env:
+#          MINDEE_API_KEY: ${{ secrets.MINDEE_API_KEY_SE_TESTS }}
+#        run: |
+#          ./vendor/bin/phpunit -c tests/phpunit.xml

.github/workflows/pull-request.yml

@@ -13,13 +13,16 @@ jobs:
   static-analysis:
     uses: ./.github/workflows/_static-analysis.yml
     needs: workflow-lint
+  build-bernard-ledit:
+    uses: ./.github/workflows/_build-bernard-ledit.yml
+    needs: workflow-lint
   test-units:
     uses: ./.github/workflows/_test-units.yml
-    needs: static-analysis
+    needs: [static-analysis, build-bernard-ledit]
     secrets: inherit
   test-integrations:
     uses: ./.github/workflows/_test-integrations.yml
-    needs: test-units
+    needs: [test-units, build-bernard-ledit]
     secrets: inherit
   smoke-test:
     uses: ./.github/workflows/_test-smoke.yml

.github/workflows/push-main-branch.yml

@@ -8,9 +8,11 @@ on:
 jobs:
   static-analysis:
     uses: mindee/mindee-api-php/.github/workflows/_static-analysis.yml@main
+  build-bernard-ledit:
+    uses: mindee/mindee-api-php/.github/workflows/_build-bernard-ledit.yml@main
   test-units:
     uses: mindee/mindee-api-php/.github/workflows/_test-units.yml@main
-    needs: static-analysis
+    needs: [static-analysis, build-bernard-ledit]
     secrets: inherit
   tag:
     uses: mindee/client-lib-actions/.github/workflows/tag-version.yml@main

.gitmodules

@@ -1,3 +1,7 @@
 [submodule "tests/resources"]
 	path = tests/resources
 	url = git@github.com:mindee/client-lib-test-data.git
+[submodule "bernard-ledit"]
+	path = bernard-ledit
+	url = https://github.com/mindee/bernard-ledit.git
+	branch = add-php-bindings