fillable-pdf 1.1.2 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6759e7cfdd5a0a97c20a9e98926b6c8e40d5a31b6543407e87cfd574806564d7
-  data.tar.gz: 59cda9afff539dc1bfb3ef194e4cb6a83c5208d8287dbfc8ed35a15bd5788829
+  metadata.gz: 9ef1adfa571c40a68f117e48e73917ef837207c8c2888a449672f2fa07664873
+  data.tar.gz: fb5c2c786c58b1635c37534381ae5ac106aaa0694e7839ec73acdaa331c863d5
 SHA512:
-  metadata.gz: c6f97c5a48a92f0606bd6121d99b2ce35f1fe7fffe5983ef50332a66b397242f628d306e1cc29d604c15f223747c0e5c5c7229d55e6da7cf0a0712911060c4d7
-  data.tar.gz: 5a8a6633a6f63b9a931ed3e7964bdb05a3ca0902583fe4e31ce1c3ee7af1c8973e39e2aebfee9a35afe2cec8fc1fef4cd8ea379dd26d5ecbaefef8b16502e177
+  metadata.gz: 86ad2b2c634818d159e2f7b710d2d38c5e726eecf9c809e8b19466cc2f842f8af9633b0900004b0f98031741a2680f5aff2bbf40f4448161d0590a2141630192
+  data.tar.gz: e940b9d5908efb0fae7b7975b0ec7878b78876fccc07c5a08c9a7e1575fa38e4829ae0a41290a791ac6e8d0d21dd97024e14c65700baf3e1f01d14b0ba7f02c7

data/README.md

@@ -6,14 +6,12 @@
 [![JDK](https://img.shields.io/badge/JDK-8%20to%2026-007396?logo=openjdk&logoColor=white)](https://github.com/vkononov/fillable-pdf/blob/main/.github/workflows/test.yml)
 [![Test Matrix](https://img.shields.io/github/actions/workflow/status/vkononov/fillable-pdf/test.yml?branch=main&label=Test%20Matrix&logo=github)](https://github.com/vkononov/fillable-pdf/actions/workflows/test.yml)
 [![Lint](https://img.shields.io/github/actions/workflow/status/vkononov/fillable-pdf/lint.yml?branch=main&label=Lint&logo=github)](https://github.com/vkononov/fillable-pdf/actions/workflows/lint.yml)
-[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/license/MIT)
 
 FillablePDF is an extremely simple and lightweight utility that bridges iText and Ruby in order to fill out fillable PDF forms or extract field values from previously filled out PDF forms.
 
 Supports **Ruby 2.4 → latest** and **JDK 8 → latest**, with the full Ruby/Java matrix tested daily in CI.
 
-[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/yellow_img.png)](https://www.buymeacoffee.com/vkononov)
-
 ## Known Issues
 
 1. Phusion Passenger's [smart spawning](https://www.phusionpassenger.com/library/indepth/ruby/spawn_methods/#the-smart-spawning-method) is not supported. Please see [Deployment with Phusion Passenger + Nginx](#deployment-with-phusion-passenger--nginx) for more information.
@@ -231,7 +229,7 @@ An instance of `FillablePDF` has the following methods at its disposal:
     pdf.set_field('first_name', 'Richard', generate_appearance: false)
     ```
 
-* `def set_fields(fields, generate_appearance: nil)`
+* `set_fields(fields, generate_appearance: nil)`
     *Sets the values of multiple fields given a set of unique field names and values, with an optional `generate_appearance` directive.*
 
     ```ruby
@@ -319,7 +317,7 @@ An instance of `FillablePDF` has the following methods at its disposal:
     # result: document is saved in a given path with flattening
     ```
 
-    **NOTE:** Saving the file automatically closes the input file, so you would need to reinitialize the `FillabePDF` class before making any more changes or saving another copy.
+    **NOTE:** Saving the file automatically closes the input file, so you would need to reinitialize the `FillablePDF` class before making any more changes or saving another copy.
 
 * `save_as!(file_path, flatten: false)`
     *Saves the filled out PDF document in a given path and flattens it if requested. Raises an error if the path matches the current file (use save() instead).*
@@ -454,15 +452,18 @@ Naturally, there are many downsides (in terms of efficiency, scalability, securi
 
 ## Example
 
-The following [example.rb](example/run.rb) with [input.pdf](example/input.pdf) is located in the [example](example) directory. It uses all of the methods that are described above and generates the output files [output.pdf](example/output.pdf) and [output.flat.pdf](example/output.flat.pdf).
+The following [run.rb](example/run.rb) with [input.pdf](example/input.pdf) is located in the [example](example) directory. It uses most of the methods that are described above and generates the output files [output.pdf](example/output.pdf) and [output.flat.pdf](example/output.flat.pdf).
 
 ```ruby
 require_relative '../lib/fillable-pdf'
 
+# Get the directory where this script is located
+EXAMPLE_DIR = __dir__
+
 BASE64_PHOTO = 'iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==' # rubocop:disable Layout/LineLength
 
 # opening a fillable PDF
-pdf = FillablePDF.new('input.pdf')
+pdf = FillablePDF.new(File.join(EXAMPLE_DIR, 'input.pdf'))
 
 # total number of fields
 if pdf.any_fields?
@@ -475,12 +476,15 @@ puts
 
 # setting form fields
 pdf.set_fields({first_name: 'Richard', last_name: 'Rahl'})
-pdf.set_fields({football: 'Yes', baseball: 'Yes', basketball: 'Yes', nascar: 'Yes', hockey: 'Yes', rugby: 'Yes'}, generate_appearance: false)
+pdf.set_fields(
+  {football: 'Yes', baseball: 'Yes', basketball: 'Yes', nascar: 'Yes', hockey: 'Yes', rugby: 'Yes'},
+  generate_appearance: false
+)
 pdf.set_field(:date, Time.now.strftime('%B %e, %Y'))
 pdf.set_field(:newsletter, 'Off') # uncheck the checkbox
 pdf.set_field(:language, 'dart') # select a radio button option
 pdf.set_image_base64(:photo, BASE64_PHOTO)
-pdf.set_image(:signature, 'signature.png')
+pdf.set_image(:signature, File.join(EXAMPLE_DIR, 'signature.png'))
 
 # list of fields
 puts "Fields hash: #{pdf.fields}"
@@ -517,11 +521,11 @@ pdf.remove_field :marketing
 puts "Removed field 'marketing'"
 
 # saving the filled out PDF in another file
-pdf.save_as('output.pdf')
+pdf.save_as(File.join(EXAMPLE_DIR, 'output.pdf'))
 
 # saving another copy of the filled out PDF in another file and making it non-editable
-pdf = FillablePDF.new('output.pdf')
-pdf.save_as 'output.flat.pdf', flatten: true
+pdf = FillablePDF.new(File.join(EXAMPLE_DIR, 'output.pdf'))
+pdf.save_as File.join(EXAMPLE_DIR, 'output.flat.pdf'), flatten: true
 
 # closing the document
 pdf.close
@@ -530,19 +534,19 @@ pdf.close
 The example above produces the following output and also generates the output file [output.pdf](example/output.pdf).
 
 ```text
-The form has a total of 16 fields.
+The form has a total of 14 fields.
 
-Fields hash: {:last_name=>"Rahl", :first_name=>"Richard", :football=>"Yes", :baseball=>"Yes", :basketball=>"Yes", :hockey=>"Yes", :date=>"November 16, 2021", :newsletter=>"Off", :nascar=>"Yes", :language=>"dart", :"language.1"=>"dart", :"language.2"=>"dart", :"language.3"=>"dart", :"language.4"=>"dart", :signature=>"", :photo=>""}
+Fields hash: {last_name: "Rahl", first_name: "Richard", football: "Yes", baseball: "Yes", basketball: "Yes", date: "August 12, 2026", newsletter: "Off", nascar: "Yes", language: "dart", signature: "", photo: "", rugby: "Yes", hockey: "Yes", marketing: ""}
 
-Keys: [:last_name, :first_name, :football, :baseball, :basketball, :hockey, :date, :newsletter, :nascar, :language, :"language.1", :"language.2", :"language.3", :"language.4", :signature, :photo]
+Keys: [:last_name, :first_name, :football, :baseball, :basketball, :date, :newsletter, :nascar, :language, :signature, :photo, :rugby, :hockey, :marketing]
 
-Values: ["Rahl", "Richard", "Yes", "Yes", "Yes", "Yes", "November 16, 2021", "Off", "Yes", "dart", "dart", "dart", "dart", "dart", "", ""]
+Values: ["Rahl", "Richard", "Yes", "Yes", "Yes", "August 12, 2026", "Off", "Yes", "dart", "", "", "Yes", "Yes", ""]
 
 Field 'football' is of type BUTTON
 
 Renamed field 'last_name' to 'surname'
 
-Removed field 'nascar'
+Removed field 'marketing'
 ```
 
 ## Contributing
@@ -556,6 +560,6 @@ Removed field 'nascar'
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/license/MIT).
 
-However, you must also adhere to the [iText License](https://github.com/itext/itext7) when using this gem in your project.
+However, you must also adhere to the [iText License](https://github.com/itext/itext-java) when using this gem in your project.

data/lib/fillable-pdf/version.rb

@@ -1,3 +1,3 @@
 class FillablePDF
-  VERSION = '1.1.2'
+  VERSION = '1.1.4'
 end

data/lib/fillable-pdf.rb

@@ -5,6 +5,7 @@ require_relative 'fillable-pdf/errors'
 require 'base64'
 require 'securerandom'
 require 'tmpdir'
+require 'tempfile'
 
 class FillablePDF # rubocop:disable Metrics/ClassLength
   include SuppressWarnings
@@ -128,7 +129,7 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   #   @param [String|Symbol] key the field name
   #   @param [String|Symbol] file_path the name of the image file or image path
   #   @return [self] returns self for method chaining
-  #   @raise [FileOperationError] if the image file is not found
+  #   @raise [FileOperationError] if the image file is not found or the field has no visible area
   #   @raise [FieldNotFoundError] if the field does not exist
   #
   def set_image(key, file_path) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
@@ -136,13 +137,7 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
     raise FileOperationError, "File <#{file_path}> is not found" unless File.exist?(file_path)
 
     begin
-      field = pdf_field(key)
-      widgets = field.getWidgets
-      widget_dict = suppress_warnings { widgets.isEmpty ? field.getPdfObject : widgets.get(0).getPdfObject }
-      orig_rect = widget_dict.getAsRectangle(ITEXT::PdfName.Rect)
-
-      border_style = field.getWidgets.get(0).getBorderStyle
-      border_width = border_style.nil? ? 0 : border_style.getWidth
+      widget_dict, orig_rect, border_width = image_placement(key)
 
       bounding_rectangle = ITEXT::Rectangle.new(
         orig_rect.getWidth - (border_width * 2),
@@ -165,6 +160,8 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
       widget_dict.put(ITEXT::PdfName.AP, pdf_dict)
       pdf_dict.put(ITEXT::PdfName.N, pdf_form_x_object.getPdfObject)
       widget_dict.setModified
+    rescue FileOperationError
+      raise
     rescue StandardError => e
       raise FileOperationError, "Failed to set image for field '#{key}': #{e.message}"
     end
@@ -299,15 +296,15 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   #
   def save(flatten: false)
     ensure_document_open
-    tmp_file = "#{Dir.tmpdir}/#{SecureRandom.uuid}"
-    save_as(tmp_file, flatten: flatten)
-    FileUtils.mv tmp_file, @file_path
+    write_document(@file_path, flatten: flatten)
     self
+  rescue StandardError => e
+    raise FileOperationError, "Failed to save file `#{@file_path}`: #{e.message}"
   end
 
   ##
   # Saves the filled out PDF document in a given path and flattens it if requested.
-  # If the path matches the current file path, it will call save() instead.
+  # The destination is replaced only after the document has been finalized.
   #
   #   @param [String] file_path the name of the PDF file or file path
   #   @param [Boolean] flatten true if PDF should be flattened, false otherwise
@@ -316,12 +313,7 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   #
   def save_as(file_path, flatten: false)
     ensure_document_open
-    if @file_path == file_path
-      save(flatten: flatten)
-      return self
-    end
-
-    File.open(file_path, 'wb') { |f| f.write(finalize(flatten: flatten)) && f.close }
+    write_document(file_path, flatten: flatten)
     self
   rescue StandardError => e
     raise FileOperationError, "Failed to save file `#{file_path}`: #{e.message}"
@@ -339,9 +331,12 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
   #
   def save_as!(file_path, flatten: false)
     ensure_document_open
-    raise InvalidArgumentError, 'Cannot save_as! to the same file path. Use save() instead.' if @file_path == file_path
+    if same_source_file?(file_path)
+      raise InvalidArgumentError,
+            'Cannot save_as! to the same file path. Use save() instead.'
+    end
 
-    File.open(file_path, 'wb') { |f| f.write(finalize(flatten: flatten)) && f.close }
+    write_document(file_path, flatten: flatten)
     self
   rescue InvalidArgumentError
     raise
@@ -373,6 +368,29 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
 
   private
 
+  def same_source_file?(file_path)
+    File.expand_path(@file_path.to_s) == File.expand_path(file_path.to_s) ||
+      (File.exist?(file_path) && File.identical?(@file_path, file_path))
+  end
+
+  # Keep the existing destination intact until finalization and writing succeed.
+  # Resolve symlinks so saving through one preserves the link itself.
+  def write_document(file_path, flatten:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    destination = File.expand_path(file_path.to_s)
+    destination = File.realpath(destination) if File.symlink?(destination)
+    mode = File.stat(destination).mode & 0o777 if File.exist?(destination)
+    temporary = Tempfile.new(['.fillable-pdf-', '.pdf'], File.dirname(destination))
+    temporary.binmode
+    temporary.write(finalize(flatten: flatten))
+    temporary.flush
+    temporary.fsync
+    temporary.chmod(mode) if mode
+    temporary.close
+    File.rename(temporary.path, destination)
+  ensure
+    temporary&.close!
+  end
+
   ##
   # Writes the contents of the modified fields to the previously opened PDF file.
   #
@@ -393,6 +411,20 @@ class FillablePDF # rubocop:disable Metrics/ClassLength
     field
   end
 
+  # Dictionary, rectangle and border width of the field's first widget, falling
+  # back to the field itself when it has no widget annotations.
+  def image_placement(key)
+    field = pdf_field(key)
+    widgets = field.getWidgets
+    widget = widgets.isEmpty ? nil : widgets.get(0)
+    widget_dict = suppress_warnings { (widget || field).getPdfObject }
+    rect = widget_dict.getAsRectangle(ITEXT::PdfName.Rect)
+    raise FileOperationError, "Field '#{key}' has no visible area to place an image in" if rect.nil?
+
+    border_style = widget&.getBorderStyle
+    [widget_dict, rect, border_style.nil? ? 0 : border_style.getWidth]
+  end
+
   def validate_input(key, value)
     validate_field_name(key)
     raise InvalidArgumentError, 'Field value cannot be nil' if value.nil?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fillable-pdf
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.4
 platform: ruby
 authors:
 - Vadim Kononov
@@ -51,9 +51,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
-description: FillablePDF is an extremely simple and lightweight utility that bridges
-  iText and Ruby in order to fill out fillable PDF forms or extract field values from
-  previously filled out PDF forms.
+description: Ruby wrapper for iText to work with AcroForm PDFs. Fill and read text
+  fields, checkboxes and radio buttons, add images to fields, rename or remove fields,
+  and flatten forms.
 email:
 - vadim@konoson.com
 executables: []
@@ -96,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - JDK >= 8
-rubygems_version: 4.0.10
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Fill out or extract field values from simple fillable PDF forms using iText.
+summary: Fill, read, flatten and edit PDF form fields in Ruby with the iText engine
 test_files: []