PDFify Ruby Gem

Ruby client library for the PDFify HTML-to-PDF API. A DocRaptor alternative at 50% cheaper pricing.

Installation

Add this line to your application's Gemfile:

gem 'pdfify'

And then execute:

bundle install

Or install it yourself as:

gem install pdfify

Quick Start

require 'pdfify'

# Configure with your API key
PDFify.configure do |config|
  config.api_key = "pfy_live_xxxxxxxxxx"
  config.base_url = "https://api.pdfify.example.com"  # optional
  config.timeout = 60  # optional, default is 60 seconds
end

# Convert HTML to PDF
pdf = PDFify.convert(
  html: "<html><body><h1>Hello World!</h1></body></html>"
)

# Save to file
File.binwrite("output.pdf", pdf)

Usage

Basic Conversion

# Simple HTML conversion
pdf = PDFify.convert(html: "<h1>Hello!</h1>")
File.binwrite("hello.pdf", pdf)

Using Client Instance

# Create a client instance
client = PDFify::Client.new

# Convert HTML
pdf = client.convert(
  html: "<html><body>Content here</body></html>"
)

Test/Sandbox Mode

Use test: true or sandbox: true to generate PDFs without counting against your quota:

pdf = PDFify.convert(
  html: "<h1>Test</h1>",
  test: true  # doesn't count against quota
)

Advanced Options

pdf = PDFify.convert(
  html: "<h1>Advanced</h1>",
  profile: "docraptor",           # CSS profile compatibility
  css: "body { color: red; }",    # Additional CSS
  auto_compat: true,               # Auto-detect template engine
  template_engine: "pdfshift"     # Specify engine explicitly
)

Error Handling

begin
  pdf = PDFify.convert(html: "<h1>Test</h1>")
  File.binwrite("output.pdf", pdf)
rescue PDFify::QuotaExceededError => e
  puts "Quota exceeded: #{e.message}"
rescue PDFify::ValidationError => e
  puts "Invalid input: #{e.message}"
rescue PDFify::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue PDFify::APIError => e
  puts "API error: #{e.message}"
end

Available Error Classes

  • PDFify::APIError - Base error class
  • PDFify::NetworkError - Connection/network errors
  • PDFify::AuthenticationError - Invalid API key
  • PDFify::ValidationError - Invalid parameters (400)
  • PDFify::QuotaExceededError - Monthly quota exceeded (403)
  • PDFify::ContentTooLargeError - HTML content too large (413)
  • PDFify::ServerError - Server-side errors (500)
  • PDFify::ConfigurationError - Missing/invalid configuration

Configuration

PDFify.configure do |config|
  # Required: Your PDFify API key
  config.api_key = "pfy_live_xxxxxxxxxx"

  # Optional: API base URL (default: https://pdfify.example.com)
  config.base_url = "https://api.pdfify.example.com"

  # Optional: Request timeout in seconds (default: 60)
  config.timeout = 60
end

Environment Variables

You can also set the API key via environment variable:

PDFify.configure do |config|
  config.api_key = ENV['PDFIFY_API_KEY']
end

Integration with Rails

Initializer

Create config/initializers/pdfify.rb:

PDFify.configure do |config|
  config.api_key = Rails.application.credentials.pdfify_api_key
  # Or use ENV: config.api_key = ENV['PDFIFY_API_KEY']
end

Controller Example

class ReportsController < ApplicationController
  def download_pdf
    html = render_to_string(template: "reports/invoice", layout: "pdf")

    pdf = PDFify.convert(html: html)

    send_data pdf,
              type: "application/pdf",
              disposition: "attachment",
              filename: "invoice-#{@invoice.id}.pdf"
  end
end

Service Object Example

class InvoicePdfGenerator
  def initialize(invoice)
    @invoice = invoice
  end

  def generate
    html = ApplicationController.render(
      template: "invoices/show",
      layout: "pdf",
      assigns: { invoice: @invoice }
    )

    PDFify.convert(html: html)
  rescue PDFify::APIError => e
    Rails.logger.error "PDF generation failed: #{e.message}"
    raise
  end
end

# Usage:
pdf = InvoicePdfGenerator.new(@invoice).generate

Replacing DocRaptor

If you're migrating from DocRaptor, here's a comparison:

DocRaptor:

DocRaptor.configure do |config|
  config.username = "YOUR_API_KEY"
end

docraptor = DocRaptor::DocApi.new
pdf = docraptor.create_doc(
  document_content: html,
  document_type: "pdf",
  test: true
)

PDFify:

PDFify.configure do |config|
  config.api_key = "YOUR_API_KEY"
end

pdf = PDFify.convert(
  html: html,
  test: true
)

It's that simple! Just swap the gem and update your configuration.

Development & Publishing Guide

Building the Gem Locally

Follow these steps to build and test the gem:

1. Install Dependencies

cd pdfify-ruby
bundle install

2. Build the Gem

gem build pdfify.gemspec

This creates a .gem file like pdfify-0.1.0.gem.

3. Test Locally (Without Publishing)

Install the gem locally to test it:

gem install ./pdfify-0.1.0.gem

Or in a Rails app's Gemfile:

gem 'pdfify', path: '../pdfify-ruby'

Then run bundle install.

4. Test in IRB

irb

require 'pdfify'

PDFify.configure do |config|
  config.api_key = "pfy_test_xxxxxxxxxx"
  config.base_url = "http://localhost:3000"  # Your local PDFify server
end

# Test it
pdf = PDFify.convert(html: "<h1>Test</h1>", test: true)
File.binwrite("test.pdf", pdf)

Publishing to RubyGems.org

Prerequisites

  1. Create a RubyGems.org account at https://rubygems.org
  2. Get your API key: 
    curl -u YOUR_USERNAME https://rubygems.org/api/v1/api_key.yaml > ~/.gem/credentials
chmod 0600 ~/.gem/credentials

Step-by-Step Publishing

1. Prepare Your Gem

Make sure all files are ready:

  • [ ] Update version in lib/pdfify/version.rb
  • [ ] Update gemspec with correct author/email/homepage
  • [ ] Create LICENSE.txt (MIT license recommended)
  • [ ] Create CHANGELOG.md documenting changes
  • [ ] Test thoroughly
2. Build the Gem
gem build pdfify.gemspec
3. Push to RubyGems
gem push pdfify-0.1.0.gem

You'll see output like:

Pushing gem to https://rubygems.org...
Successfully registered gem: pdfify (0.1.0)
4. Verify

Visit https://rubygems.org/gems/pdfify to see your published gem!

5. Install Anywhere

Now anyone can install it:

gem install pdfify

Or in a Gemfile:

gem 'pdfify', '~> 0.1.0'

Publishing Updates

When you need to release a new version:

  1. Update version in lib/pdfify/version.rb:

    VERSION = "0.2.0"

  2. Update CHANGELOG.md with changes

  3. Build and push:

    gem build pdfify.gemspec
gem push pdfify-0.2.0.gem

Yanking a Version (Emergency)

If you need to unpublish a broken version:

gem yank pdfify -v 0.1.0

Best Practices

  • Use Semantic Versioning: MAJOR.MINOR.PATCH
    • MAJOR: Breaking changes
    • MINOR: New features (backward compatible)
    • PATCH: Bug fixes
  • Always test locally before publishing
  • Keep CHANGELOG.md updated
  • Tag releases in git: git tag v0.1.0 && git push --tags
  • Never publish with sensitive data (API keys, passwords)

Setting Up GitHub Repo (Optional but Recommended)

cd pdfify-ruby
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/pdfify-ruby.git
git push -u origin main

Then update gemspec with correct GitHub URLs.

Testing

Run the test suite (when tests are added):

bundle exec rspec

API Reference

PDFify.configure { |config| ... }

Configure the global PDFify settings.

Parameters:

  • config.api_key (String) - Your PDFify API key (required)
  • config.base_url (String) - API base URL (optional, default: https://pdfify.example.com)
  • config.timeout (Integer) - Request timeout in seconds (optional, default: 60)

PDFify.convert(html:, **options)

Convert HTML to PDF.

Parameters:

  • html (String) - HTML content to convert (required)
  • test (Boolean) - Enable test/sandbox mode (optional)
  • sandbox (Boolean) - Alias for test (optional)
  • profile (String) - CSS profile to use (optional)
  • css (String) - Additional CSS to inject (optional)
  • auto_compat (Boolean) - Enable auto-compatibility mode (optional)
  • template_engine (String) - Specify template engine (optional)

Returns:

  • (String) Binary PDF data

Raises:

  • ArgumentError if HTML is missing
  • PDFify::ConfigurationError if API key is not configured
  • PDFify::APIError and subclasses for API errors

PDFify::Client.new(config = nil)

Create a new client instance.

Parameters:

  • config (PDFify::Configuration) - Custom configuration (optional, uses global config if nil)

Returns:

  • PDFify::Client instance

License

The gem is available as open source under the terms of the MIT License.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/pdfify-ruby.

Support