fastqr 1.0.1

data/bindings/php/src/FastQR.php

@@ -0,0 +1,316 @@
+<?php
+
+/**
+ * FastQR - Fast QR Code Generator
+ * PHP Binding using FFI
+ *
+ * Copyright (C) 2025 FastQR Project
+ * Licensed under LGPL-2.1
+ */
+
+namespace FastQR;
+
+use FFI;
+use RuntimeException;
+
+class FastQR
+{
+    private static ?FFI $ffi = null;
+    private static bool $initialized = false;
+
+    /**
+     * Initialize FFI
+     */
+    private static function init(): void
+    {
+        if (self::$initialized) {
+            return;
+        }
+
+        // Detect platform
+        $os = PHP_OS_FAMILY === 'Darwin' ? 'macos' : (PHP_OS_FAMILY === 'Linux' ? 'linux' : 'unknown');
+        $arch = php_uname('m');
+        if ($arch === 'x86_64' || $arch === 'amd64') {
+            $arch = 'x86_64';
+        } elseif ($arch === 'aarch64' || $arch === 'arm64') {
+            $arch = 'arm64';
+        }
+        $platform = "$os-$arch";
+        $ext = $os === 'macos' ? 'dylib' : 'so';
+
+        // Try to find the library (pre-built first, then system)
+        $libPaths = [
+            __DIR__ . "/../../prebuilt/$platform/lib/libfastqr.$ext",  // Pre-built binary
+            '/usr/local/lib/libfastqr.' . $ext,                         // System install
+            '/usr/lib/libfastqr.' . $ext,
+            __DIR__ . '/../../../build/libfastqr.' . $ext,               // Local build
+        ];
+
+        $libPath = null;
+        foreach ($libPaths as $path) {
+            if (file_exists($path)) {
+                $libPath = $path;
+                break;
+            }
+        }
+
+        if ($libPath === null) {
+            throw new RuntimeException(
+                "FastQR library not found for platform: $platform\n" .
+                "Please install fastqr or build from source."
+            );
+        }
+
+        // Define C interface
+        $header = '
+            typedef struct {
+                int size;
+                int optimize_size;
+                unsigned char foreground_r;
+                unsigned char foreground_g;
+                unsigned char foreground_b;
+                unsigned char background_r;
+                unsigned char background_g;
+                unsigned char background_b;
+                int ec_level;
+                const char* logo_path;
+                int logo_size_percent;
+                const char* format;
+                int quality;
+            } QROptions;
+
+            bool fastqr_generate(const char* data, const char* output_path, QROptions* options);
+            const char* fastqr_version(void);
+        ';
+
+        self::$ffi = FFI::cdef($header, $libPath);
+        self::$initialized = true;
+    }
+
+    /**
+     * Generate QR code
+     *
+     * @param string $data Data to encode (UTF-8 supported)
+     * @param string $outputPath Path to save the QR code image
+     * @param array $options Generation options
+     * @return bool true if successful
+     *
+     * @throws RuntimeException if generation fails
+     *
+     * @example
+     * ```php
+     * use FastQR\FastQR;
+     *
+     * // Basic usage
+     * FastQR::generate('Hello World', 'qr.png');
+     *
+     * // With options
+     * FastQR::generate('Hello', 'qr.png', [
+     *     'size' => 500,
+     *     'optimizeSize' => true,
+     *     'foreground' => [255, 0, 0],
+     *     'background' => [255, 255, 200],
+     *     'errorLevel' => 'H'
+     * ]);
+     *
+     * // With logo
+     * FastQR::generate('Company', 'qr.png', [
+     *     'size' => 600,
+     *     'logo' => 'logo.png',
+     *     'logoSize' => 25
+     * ]);
+     *
+     * // UTF-8 support
+     * FastQR::generate('Xin chào Việt Nam! 🇻🇳', 'vietnamese.png');
+     * FastQR::generate('こんにちは日本', 'japanese.png');
+     * ```
+     */
+    public static function generate(string $data, string $outputPath, array $options = []): bool
+    {
+        self::init();
+
+        if (empty($data)) {
+            throw new RuntimeException('Data cannot be empty');
+        }
+        if (empty($outputPath)) {
+            throw new RuntimeException('Output path cannot be empty');
+        }
+
+        // Create options struct
+        $opts = self::$ffi->new('QROptions');
+
+        // Size (preferred) or width/height (backward compatibility)
+        if (isset($options['size'])) {
+            $opts->size = $options['size'];
+        } elseif (isset($options['width']) || isset($options['height'])) {
+            $opts->size = $options['width'] ?? $options['height'] ?? 300;
+        } else {
+            $opts->size = 300;
+        }
+
+        // Optimize size
+        $opts->optimize_size = $options['optimizeSize'] ?? false ? 1 : 0;
+
+        // Foreground color
+        $fg = $options['foreground'] ?? [0, 0, 0];
+        $opts->foreground_r = $fg[0] ?? 0;
+        $opts->foreground_g = $fg[1] ?? 0;
+        $opts->foreground_b = $fg[2] ?? 0;
+
+        // Background color
+        $bg = $options['background'] ?? [255, 255, 255];
+        $opts->background_r = $bg[0] ?? 255;
+        $opts->background_g = $bg[1] ?? 255;
+        $opts->background_b = $bg[2] ?? 255;
+
+        // Error correction level
+        $ecLevel = $options['errorLevel'] ?? 'M';
+        $opts->ec_level = match($ecLevel) {
+            'L' => 0,
+            'M' => 1,
+            'Q' => 2,
+            'H' => 3,
+            default => 1
+        };
+
+        // Logo
+        $opts->logo_path = $options['logo'] ?? null;
+        $opts->logo_size_percent = $options['logoSize'] ?? 20;
+
+        // Format and quality
+        $opts->format = $options['format'] ?? 'png';
+        $opts->quality = $options['quality'] ?? 95;
+
+        // Call C function
+        $result = self::$ffi->fastqr_generate($data, $outputPath, FFI::addr($opts));
+
+        if (!$result) {
+            throw new RuntimeException('Failed to generate QR code');
+        }
+
+        return true;
+    }
+
+    /**
+     * Get library version
+     *
+     * @return string Version string
+     */
+    public static function version(): string
+    {
+        self::init();
+        return self::$ffi->fastqr_version();
+    }
+
+    /**
+     * Generate multiple QR codes in batch mode (7x faster!)
+     *
+     * @param array $dataArray Array of strings to encode
+     * @param string $outputDir Directory to save QR codes (will be created if it doesn't exist)
+     * @param array $options Generation options (same as generate)
+     * @return array Result with 'success' and 'failed' counts
+     *
+     * @throws RuntimeException if generation fails
+     *
+     * @example
+     * ```php
+     * use FastQR\FastQR;
+     *
+     * // Batch generation
+     * $data = ['QR 1', 'QR 2', 'QR 3'];
+     * FastQR::generateBatch($data, 'output_dir/', ['size' => 500]);
+     * // Creates: output_dir/1.png, output_dir/2.png, output_dir/3.png
+     * ```
+     */
+    public static function generateBatch(array $dataArray, string $outputDir, array $options = []): array
+    {
+        if (empty($dataArray)) {
+            throw new RuntimeException('Data array cannot be empty');
+        }
+        if (empty($outputDir)) {
+            throw new RuntimeException('Output directory cannot be empty');
+        }
+
+        // Create output directory
+        if (!is_dir($outputDir)) {
+            mkdir($outputDir, 0755, true);
+        }
+
+        // Create temporary batch file
+        $tempFile = tempnam(sys_get_temp_dir(), 'fastqr_batch_') . '.txt';
+        try {
+            file_put_contents($tempFile, implode("\n", $dataArray));
+
+            // Find CLI binary
+            $os = PHP_OS_FAMILY === 'Darwin' ? 'macos' : (PHP_OS_FAMILY === 'Linux' ? 'linux' : 'unknown');
+            $arch = php_uname('m');
+            if ($arch === 'x86_64' || $arch === 'amd64') {
+                $arch = 'x86_64';
+            } elseif ($arch === 'aarch64' || $arch === 'arm64') {
+                $arch = 'arm64';
+            }
+            $platform = "$os-$arch";
+
+            $cliPaths = [
+                __DIR__ . "/../../prebuilt/$platform/bin/fastqr",
+                '/usr/local/bin/fastqr',
+                __DIR__ . '/../../../build/fastqr',
+            ];
+
+            $cliPath = null;
+            foreach ($cliPaths as $path) {
+                if (file_exists($path)) {
+                    $cliPath = $path;
+                    break;
+                }
+            }
+
+            if ($cliPath === null) {
+                throw new RuntimeException("FastQR CLI not found for platform: $platform");
+            }
+
+            // Build command
+            $cmd = escapeshellarg($cliPath) . ' -F ' . escapeshellarg($tempFile) . ' ' . escapeshellarg($outputDir);
+
+            if (isset($options['size'])) {
+                $cmd .= ' -s ' . (int)$options['size'];
+            }
+            if (!empty($options['optimizeSize'])) {
+                $cmd .= ' -o';
+            }
+            if (isset($options['foreground'])) {
+                $fg = $options['foreground'];
+                $cmd .= ' -f ' . implode(',', $fg);
+            }
+            if (isset($options['background'])) {
+                $bg = $options['background'];
+                $cmd .= ' -b ' . implode(',', $bg);
+            }
+            if (isset($options['errorLevel'])) {
+                $cmd .= ' -e ' . escapeshellarg($options['errorLevel']);
+            }
+            if (isset($options['logo'])) {
+                $cmd .= ' -l ' . escapeshellarg($options['logo']);
+            }
+            if (isset($options['logoSize'])) {
+                $cmd .= ' -p ' . (int)$options['logoSize'];
+            }
+            if (isset($options['quality'])) {
+                $cmd .= ' -q ' . (int)$options['quality'];
+            }
+
+            exec($cmd . ' 2>&1', $output, $returnCode);
+
+            if ($returnCode !== 0) {
+                throw new RuntimeException('Batch generation failed: ' . implode("\n", $output));
+            }
+
+            return ['success' => count($dataArray), 'failed' => 0];
+        } finally {
+            if (file_exists($tempFile)) {
+                unlink($tempFile);
+            }
+        }
+    }
+}
+

data/bindings/php/tests/FastQRTest.php

@@ -0,0 +1,97 @@
+<?php
+
+/**
+ * FastQR PHP Tests
+ */
+
+namespace FastQR\Tests;
+
+use FastQR\FastQR;
+use PHPUnit\Framework\TestCase;
+
+class FastQRTest extends TestCase
+{
+    private string $outputDir;
+
+    protected function setUp(): void
+    {
+        $this->outputDir = __DIR__ . '/output';
+        if (!is_dir($this->outputDir)) {
+            mkdir($this->outputDir, 0755, true);
+        }
+    }
+
+    public function testVersion(): void
+    {
+        $version = FastQR::version();
+        $this->assertNotEmpty($version);
+        $this->assertMatchesRegularExpression('/^\d+\.\d+\.\d+$/', $version);
+    }
+
+    public function testBasicGeneration(): void
+    {
+        $output = $this->outputDir . '/basic.png';
+        $result = FastQR::generate('Hello, FastQR from PHP!', $output);
+
+        $this->assertTrue($result);
+        $this->assertFileExists($output);
+    }
+
+    public function testColoredQR(): void
+    {
+        $output = $this->outputDir . '/colored.png';
+        $result = FastQR::generate('Colored QR', $output, [
+            'width' => 500,
+            'height' => 500,
+            'foreground' => [255, 0, 0],
+            'background' => [255, 255, 200]
+        ]);
+
+        $this->assertTrue($result);
+        $this->assertFileExists($output);
+    }
+
+    public function testVietnameseText(): void
+    {
+        $output = $this->outputDir . '/vietnamese.png';
+        $result = FastQR::generate('Xin chào Việt Nam! 🇻🇳', $output);
+
+        $this->assertTrue($result);
+        $this->assertFileExists($output);
+    }
+
+    public function testJapaneseText(): void
+    {
+        $output = $this->outputDir . '/japanese.png';
+        $result = FastQR::generate('こんにちは日本', $output, [
+            'foreground' => [0, 0, 255]
+        ]);
+
+        $this->assertTrue($result);
+        $this->assertFileExists($output);
+    }
+
+    public function testHighErrorCorrection(): void
+    {
+        $output = $this->outputDir . '/high_ec.png';
+        $result = FastQR::generate('High Error Correction', $output, [
+            'errorLevel' => 'H'
+        ]);
+
+        $this->assertTrue($result);
+        $this->assertFileExists($output);
+    }
+
+    public function testEmptyDataThrowsException(): void
+    {
+        $this->expectException(\RuntimeException::class);
+        FastQR::generate('', 'output.png');
+    }
+
+    public function testEmptyOutputPathThrowsException(): void
+    {
+        $this->expectException(\RuntimeException::class);
+        FastQR::generate('Hello', '');
+    }
+}
+

data/bindings/ruby/extconf.rb

@@ -0,0 +1,29 @@
+require 'mkmf'
+
+# Check for required libraries
+unless have_library('qrencode')
+  abort "ERROR: libqrencode is required. Install it first."
+end
+
+unless have_library('vips')
+  abort "ERROR: libvips is required. Install it first."
+end
+
+# Check for headers
+unless have_header('qrencode.h')
+  abort "ERROR: qrencode.h not found"
+end
+
+unless have_header('vips/vips.h')
+  abort "ERROR: vips/vips.h not found"
+end
+
+# Add C++14 support
+$CXXFLAGS << " -std=c++14"
+
+# Set source directory
+$srcs = ['fastqr_ruby.cpp', '../../src/fastqr.cpp']
+$INCFLAGS << " -I$(srcdir)/../../include"
+
+create_makefile('fastqr/fastqr')
+

data/bindings/ruby/fastqr_ruby.cpp

@@ -0,0 +1,122 @@
+/*
+ * FastQR Ruby Binding
+ * Copyright (C) 2025 FastQR Project
+ */
+
+#include "fastqr.h"
+#include <ruby.h>
+
+static VALUE rb_mFastQR;
+static VALUE rb_cQROptions;
+
+// Convert Ruby hash to QROptions
+static fastqr::QROptions hash_to_options(VALUE opts) {
+    fastqr::QROptions options;
+
+    if (NIL_P(opts)) {
+        return options;
+    }
+
+    VALUE val;
+
+    // Size (preferred) or width/height (backward compatibility)
+    val = rb_hash_aref(opts, ID2SYM(rb_intern("size")));
+    if (!NIL_P(val)) {
+        options.size = NUM2INT(val);
+    } else {
+        // Backward compatibility: if width or height specified, use them
+        val = rb_hash_aref(opts, ID2SYM(rb_intern("width")));
+        if (!NIL_P(val)) options.size = NUM2INT(val);
+
+        val = rb_hash_aref(opts, ID2SYM(rb_intern("height")));
+        if (!NIL_P(val)) options.size = NUM2INT(val);
+    }
+
+    // Optimize size
+    val = rb_hash_aref(opts, ID2SYM(rb_intern("optimize_size")));
+    if (!NIL_P(val)) options.optimize_size = RTEST(val);
+
+    // Foreground color
+    val = rb_hash_aref(opts, ID2SYM(rb_intern("foreground")));
+    if (!NIL_P(val) && TYPE(val) == T_ARRAY) {
+        options.foreground.r = NUM2INT(rb_ary_entry(val, 0));
+        options.foreground.g = NUM2INT(rb_ary_entry(val, 1));
+        options.foreground.b = NUM2INT(rb_ary_entry(val, 2));
+    }
+
+    // Background color
+    val = rb_hash_aref(opts, ID2SYM(rb_intern("background")));
+    if (!NIL_P(val) && TYPE(val) == T_ARRAY) {
+        options.background.r = NUM2INT(rb_ary_entry(val, 0));
+        options.background.g = NUM2INT(rb_ary_entry(val, 1));
+        options.background.b = NUM2INT(rb_ary_entry(val, 2));
+    }
+
+    // Error correction level
+    val = rb_hash_aref(opts, ID2SYM(rb_intern("error_level")));
+    if (!NIL_P(val)) {
+        const char* level = StringValueCStr(val);
+        if (strcmp(level, "L") == 0) options.ec_level = fastqr::ErrorCorrectionLevel::LOW;
+        else if (strcmp(level, "M") == 0) options.ec_level = fastqr::ErrorCorrectionLevel::MEDIUM;
+        else if (strcmp(level, "Q") == 0) options.ec_level = fastqr::ErrorCorrectionLevel::QUARTILE;
+        else if (strcmp(level, "H") == 0) options.ec_level = fastqr::ErrorCorrectionLevel::HIGH;
+    }
+
+    // Logo path
+    val = rb_hash_aref(opts, ID2SYM(rb_intern("logo")));
+    if (!NIL_P(val)) {
+        options.logo_path = StringValueCStr(val);
+    }
+
+    // Logo size
+    val = rb_hash_aref(opts, ID2SYM(rb_intern("logo_size")));
+    if (!NIL_P(val)) {
+        options.logo_size_percent = NUM2INT(val);
+    }
+
+    // Quality
+    val = rb_hash_aref(opts, ID2SYM(rb_intern("quality")));
+    if (!NIL_P(val)) {
+        options.quality = NUM2INT(val);
+    }
+
+    // Format
+    val = rb_hash_aref(opts, ID2SYM(rb_intern("format")));
+    if (!NIL_P(val)) {
+        options.format = StringValueCStr(val);
+    }
+
+    return options;
+}
+
+// FastQR.generate(data, output_path, options = {})
+static VALUE rb_fastqr_generate(int argc, VALUE *argv, VALUE self) {
+    VALUE data, output_path, opts;
+    rb_scan_args(argc, argv, "21", &data, &output_path, &opts);
+
+    std::string data_str = StringValueCStr(data);
+    std::string output_str = StringValueCStr(output_path);
+    fastqr::QROptions options = hash_to_options(opts);
+
+    bool result = fastqr::generate(data_str, output_str, options);
+
+    return result ? Qtrue : Qfalse;
+}
+
+// FastQR.version
+static VALUE rb_fastqr_version(VALUE self) {
+    return rb_str_new_cstr(fastqr::version());
+}
+
+extern "C" void Init_fastqr() {
+    rb_mFastQR = rb_define_module("FastQR");
+
+    rb_define_module_function(rb_mFastQR, "generate",
+                              RUBY_METHOD_FUNC(rb_fastqr_generate), -1);
+    rb_define_module_function(rb_mFastQR, "version",
+                              RUBY_METHOD_FUNC(rb_fastqr_version), 0);
+
+    // Constants
+    rb_define_const(rb_mFastQR, "VERSION", rb_str_new_cstr(fastqr::version()));
+}
+

data/bindings/ruby/lib/fastqr/platform.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module FastQR
+  # Platform detection and pre-built binary management
+  module Platform
+    class << self
+      # Detects the current platform
+      # @return [String] Platform identifier (e.g., 'macos-arm64', 'linux-x86_64')
+      def detect
+        os = RbConfig::CONFIG['host_os']
+        arch = RbConfig::CONFIG['host_cpu']
+
+        case os
+        when /darwin/
+          case arch
+          when /arm64|aarch64/
+            'macos-arm64'
+          when /x86_64|x64/
+            'macos-x86_64'
+          else
+            raise "Unsupported macOS architecture: #{arch}"
+          end
+        when /linux/
+          case arch
+          when /x86_64|x64/
+            'linux-x86_64'
+          when /arm64|aarch64/
+            'linux-arm64'
+          else
+            raise "Unsupported Linux architecture: #{arch}"
+          end
+        else
+          raise "Unsupported platform: #{os}"
+        end
+      end
+
+      # Extracts pre-built binary from tarball
+      # @param tarball_path [String] Path to the tarball
+      # @param dest_dir [String] Destination directory
+      def extract_binary(tarball_path, dest_dir)
+        FileUtils.mkdir_p(dest_dir)
+        system("tar -xzf '#{tarball_path}' -C '#{dest_dir}'") or raise "Failed to extract #{tarball_path}"
+      end
+
+      # Finds the fastqr binary
+      # @return [String] Path to fastqr binary
+      def find_binary
+        platform = detect
+        prebuilt_dir = File.expand_path("../../prebuilt/#{platform}", __dir__)
+        binary_path = File.join(prebuilt_dir, 'fastqr')
+
+        return binary_path if File.exist?(binary_path)
+
+        # Try to extract from tarball
+        tarball_path = File.expand_path("../../prebuilt/#{platform}.tar.gz", __dir__)
+        if File.exist?(tarball_path)
+          puts "Extracting pre-built binary from #{tarball_path}..."
+          extract_binary(tarball_path, prebuilt_dir)
+
+          if File.exist?(binary_path)
+            File.chmod(0755, binary_path)
+            return binary_path
+          end
+        end
+
+        raise "Pre-built binary not found for #{platform}"
+      end
+    end
+  end
+end

data/bindings/ruby/lib/fastqr/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module FastQR
+  VERSION = "1.0.1"
+end
+