This is a followup to #3048947: Refactor HandlePdfController::populatePdf() and #3059342: Add plugin inspection to backend plugins, and a blocker for #3040901: Allow backend plugins to supply settings for the FillPdfSettingsForm.

Our FillPdfBackend plugins suffer from neither extending a PluginBase class nor using a custom Annotation type, so any changes/additions to annotations need to be resolved by the backend manager, and any changes to the interface won't be backwards compatible unless resolved in the calling code.

The second generation BackendService plugins are way better. However only a single one has been created, and it doesn't stand alone, but is called by a FillPdfBackend plugin, so just following through with converting wouldn't solve the whole problem.

After the big all-in-one conversion patch #3040901: Allow backend plugins to supply settings for the FillPdfSettingsForm got stuck, we turned to refactoring things step by step, with the aim of limiting BC layers to the minimum necessary.

We want plugins to be configurable and to contain everything that specifically belongs to them.

We also do want to support parsing and merging a PDF file that may not necessarily be contained in a FillPdfForm, but is present either as a stream or a file.

Finally, we want to switch to FieldMapping objects (and already did so in #3048947: Refactor HandlePdfController::populatePdf(), though this wasn't immediately possibly without a BC layer in HandlePdfController and an API switch on the plugins).

So our next step would be: move all BC code out of the way to a single legacy backend manager. And it turned out that this is possible, avoiding any changes to legacy plugins we still want to support, while leaving us maximum freedom on defining new plugins, see the forthcoming patch.

Manual testing steps

For each backend:

  • Configure the backend being tested.
  • Parse a PDF with it; ensure fields are detected.
  • Generate a sample PDF with it; ensure fields are detected.
  • Recommended: if the backend supports image stamping, parse a simple PDF with a Button field and map an image to it. Set a default entity with an image field, fill from it, and make sure an image appears.

Comments

Pancho created an issue. See original summary.

pancho’s picture

Issue summary: View changes
Status: Active » Needs review
Issue tags: +Needs manual testing
StatusFileSize
new68.9 KB

Here's a first patch.

I managed to handle legacy plugins using the nifty FallbackPluginManagerInterface together with handlePluginNotFound(), so there’s no need of any switch whatsoever (and #3046530: Revert: Add experimental sub-module to switch between BC and Next API may be reverted, yay!)

Note that I duplicated all backends so we can manually test and compare both that original legacy and the converted plugin. Local and manual tests on pdftk and LocalServer were passing, and so far it seems they're working exactly the same, proving we're still 100% BC. We'd still need a manual test with legacy local and FillPDF Service though.

Next step I'd be removing the duplicates.

Status: Needs review » Needs work

The last submitted patch, 2: fillpdf_introduce_pdfbackend_plugins_3060086-2.patch, failed testing. View results
- codesniffer_fixes.patch Interdiff of automated coding standards fixes only.

pancho’s picture

Status: Needs work » Needs review

Very minor deprecation warning. Ready for review.

pancho’s picture

  • Removed JavaBridgeBackend ported to the new API. Legacy support is enough.
  • Removed legacy pdftk, Local Server and FillPdfService backends. We don't need both.
  • Fixed deprecations.
  • Fixed warning message in Kernel/FillPdfBackendTest.

Note that similarity of some classes is too low, so git sees a deleted and another new file rather than a changed/renamed one. I will try to break it into two commits, so git can follow.

pancho’s picture

Assigned: Unassigned » wizonesolutions

Assigning for review and (manual) testing on FillPdfService and custom API uses.

wizonesolutions’s picture

Issue summary: View changes
wizonesolutions’s picture

There was a bug in FillPDF Service image filling; I think the wrong code from before got pasted, or something. Anyway, there's a particular array format that the XML-RPC call expects. It's even used properly in the legacy plugin. Fixed in new patch. Will test this tomorrow for BC against my implementation that currently uses LocalService directly.

wizonesolutions’s picture

Confirmed parsing works for FillPDF Service. Now checking that my code that uses the LocalService BackendService still works with this patch. I'll likely just leave it alone and port it to the new plugin type later on.

wizonesolutions’s picture

Status: Needs review » Needs work

The BackendService LocalService BC layer is perfect. Worked fine with my project.

I found some small things to note:

  1. +++ b/src/Plugin/BackendService/LocalService.php
    @@ -20,7 +16,12 @@ use Symfony\Component\DependencyInjection\ContainerInterface;
    +  private $pdfbackend;
    

    Should be $pdfBackend

  2. +++ /dev/null
    @@ -1,87 +0,0 @@
    diff --git a/src/FillPdfBackendManager.php b/src/Plugin/LegacyBackendManager.php
    
    diff --git a/src/FillPdfBackendManager.php b/src/Plugin/LegacyBackendManager.php
    similarity index 84%
    
    similarity index 84%
    rename from src/FillPdfBackendManager.php
    
    rename from src/FillPdfBackendManager.php
    rename to src/Plugin/LegacyBackendManager.php
    
    rename to src/Plugin/LegacyBackendManager.php
    index 1eb68cb..e7c1023 100644
    
    index 1eb68cb..e7c1023 100644
    --- a/src/FillPdfBackendManager.php
    
    --- a/src/FillPdfBackendManager.php
    +++ b/src/Plugin/LegacyBackendManager.php
    
    +++ b/src/Plugin/LegacyBackendManager.php
    +++ b/src/Plugin/LegacyBackendManager.php
    @@ -1,6 +1,6 @@
    

    Just leaving a comment in-issue to ensure this rename gets properly applied by patch -p1 (if not using git apply).

  3. +++ b/src/Plugin/PdfBackendInterface.php
    @@ -0,0 +1,96 @@
    +   * @return array[]
    +   *   An array of arrays containing metadata about the fields in the PDF. These
    +   *   can be iterated over and saved by the caller.
    +   *
    +   * @see \Drupal\fillpdf\Plugin\PdfBackendInterface::parseStream()
    +   */
    

    Noticed this while reviewing the function signature. Can we a bit more specific and perhaps show a sample array? It's keyed on field names, yeah?

    We could either introduce a value object that formalizes this (e.g. for those extra properties you wanted to use from PDFtk, when available)...or just document it. But as written, it's too hard for me to visualize what my plugin should be returning.

I want to run the FillPDF Service test locally one more time, and then after these tweaks, I think we're all good.

pancho’s picture

Status: Needs work » Needs review
StatusFileSize
new66.04 KB
new53.44 KB

Here's a new patch.

#10-1, #10-2: fixed.
#10-3: Returned to previous docblock. I'd like a value object here, too. But that should be a followup.

+ Many more minor improvements, standardizations, coding style, deprecations etc.

Also, git now correctly recognizes renamed files etc., so there's a little bit of noise in the interdiff, but the actual patch is smaller and less noisy.

Made sure changes from #8 didn't get lost.

All tests, both local and on DrupalCI, are passing.

pancho’s picture

Assigned: wizonesolutions » Unassigned
Issue tags: -Needs manual testing
StatusFileSize
new67.52 KB
new4.59 KB

Some more tidbits. Attached a plain diff as it's easier to read in this case.

pancho’s picture

Assigned: Unassigned » wizonesolutions
StatusFileSize
new67.63 KB
new651 bytes

Small pdftk test fix.

pancho’s picture

Assigned: wizonesolutions » Unassigned

All local tests passing again.

@wizonesolutions agrees we should move on, so let's move on!

Next one is going to be #3040901: Allow backend plugins to supply settings for the FillPdfSettingsForm.

  • Pancho committed 5c91727 on 8.x-4.x
    Issue #3060086 by Pancho, wizonesolutions: Introduce new PdfBackend...
pancho’s picture

Status: Needs review » Fixed
pancho’s picture

Status: Fixed » Needs review
Issue tags: +Needs tests
StatusFileSize
new1.03 KB

The JavaBridge backend needs a followup. We may not remove PluginBase from the plugin. Should receive tests, too.

wizonesolutions’s picture

StatusFileSize
new1.13 KB

Reroll since we moved this to the fillpdf_legacy module.

wizonesolutions’s picture

Issue tags: -Needs tests

Oh, and I think a small change like this is fine without tests. I don't really want to keep supporting the JavaBridge approach, anyway. FillPDF LocalServer has replaced it.

wizonesolutions’s picture

Status: Needs review » Fixed

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.