etTheme('dark') ->draw($canvas);

    // Right panel: Quarterly revenue breakdown
    $barChart = new BarChart(1600, 900);
    $barChart->setTitle('Revenue by Quarter')
        ->setSeries([['data' => $revenueData, 'color' => '#a78bfa']])
        ->setPlotRect(860, 80, 1540, 820)
        ->setTheme('dark')
        ->draw($canvas);

    // Overlay native GD text
    imagettftext($canvas, 28, 0, 40, 50, $textColor, self::FONT_PATH, 'Executive Dashboard');

    $filePath = self::OUTPUT_DIR . '/dashboard_' . time() . '.png';
    imagepng($canvas, $filePath);
    imagedestroy($canvas);

    return $filePath;
}

public function generateShippingLabel(string $trackingId, string $sku): array
{
    $qr = new QrCode();
    $qrPath = self::OUTPUT_DIR . '/qr_' . $trackingId . '.png';
    $qr->setContent("SHIP:$trackingId|$sku")
        ->setErrorCorrection('high')
        ->setVersion(4)
        ->renderToFile($qrPath);

    $barcode = new Barcode();
    $bcPath = self::OUTPUT_DIR . '/bc_' . $trackingId . '.png';
    $barcode->setContent($trackingId)
        ->setType('code128')
        ->setHumanReadable(true)
        ->renderToFile($bcPath);

    return [$qrPath, $bcPath];
}

}

#### Architecture Rationale
- **Lazy Canvas Allocation**: The dashboard method creates a single `GdImage` resource and reuses it. This prevents memory fragmentation and ensures consistent color profiles across panels.
- **Plot Rectangle Isolation**: `setPlotRect()` defines exact boundaries for each chart. This prevents axis labels from overlapping and guarantees predictable spacing when compositing.
- **Symbol Separation**: QR codes and barcodes live in a parallel namespace. They do not accept caller-owned canvases because quiet zones (mandatory blank margins) make pixel-level compositing ambiguous. Instead, they render standalone files that can be merged later using standard GD functions.
- **Resource Cleanup**: `imagedestroy()` is called explicitly after `imagepng()`. PHP’s garbage collector handles it eventually, but explicit destruction prevents memory accumulation in long-running workers or queue consumers.

## Pitfall Guide

Server-side visualization introduces subtle failure modes that rarely appear in browser-based rendering. The following pitfalls represent the most common production incidents.

### 1. Extension Load Order Mismatch
**Explanation**: The extension depends on `ext/gd`. If PHP loads the visualization module before GD initializes, MINIT fails and the extension refuses to load. Alphabetical `conf.d` ordering in Docker or Debian-based systems often triggers this.
**Fix**: The extension declares `ZEND_MOD_REQUIRED("gd")` internally, forcing the engine to resolve dependencies correctly. Verify load order with `php -m | grep -E 'gd|fastchart'`. If using `phpize`, ensure `ext/gd` is compiled or loaded first.

### 2. Canvas Coordinate Drift
**Explanation**: GD uses top-left origin (0,0) with Y increasing downward. Plot rectangles, font baselines, and legend positions must align precisely. Misaligned `setPlotRect()` values cause axis labels to render outside the visible area or overlap chart data.
**Fix**: Calculate plot boundaries explicitly. Reserve 60-80px for left margins (Y-axis labels), 40px for top/bottom (titles/legends), and 60px for right margins. Use `setPlotRect($x1, $y1, $x2, $y2)` with absolute pixel values, not percentages.

### 3. Font Path Resolution Failures
**Explanation**: `imagettftext()` requires absolute paths to `.ttf` or `.otf` files. Relative paths, missing fonts, or permission restrictions cause silent failures or blank text overlays.
**Fix**: Bundle fonts with your application or use system paths (`/usr/share/fonts/...`). Validate font existence at bootstrap. Set `open_basedir` to include font directories if restricted. Test rendering in CI with a headless GD environment.

### 4. Memory Bloat from Unbounded Datasets
**Explanation**: Passing arrays with 100k+ data points to chart constructors allocates proportional memory. PHP’s memory limit is often set to 128MB or 256MB, which can be exhausted during rendering.
**Fix**: Downsample data before rendering. Use aggregation (daily averages instead of minute-by-minute), or implement pagination. For financial charts, limit visible points to 300-500. Monitor `memory_get_peak_usage()` during benchmarking.

### 5. QR Error Correction Misconfiguration
**Explanation**: QR codes support four ECC levels (L, M, Q, H). Using low correction on damaged labels or high correction on dense data increases module size unnecessarily, breaking scanner compatibility or wasting space.
**Fix**: Match ECC to environment. Use `low` or `medium` for clean digital displays. Use `high` for physical labels exposed to wear, dirt, or partial occlusion. Validate scanner readability in production conditions before deployment.

### 6. Ignoring Thread Safety (ZTS vs NTS)
**Explanation**: PHP extensions must compile against the correct thread-safety model. NTS builds fail on ZTS PHP (and vice versa), causing `PHP Warning: PHP Startup: Unable to load dynamic library`.
**Fix**: Check `php -i | grep "Thread Safety"`. Compile or install the matching variant. Docker images based on `php:8.3-fpm` typically use NTS. Apache MPM Worker or PHP-PM require ZTS. Never mix binaries across builds.

### 7. Overusing `renderToFile` in High-Throughput APIs
**Explanation**: Writing to disk on every request introduces I/O latency, filesystem contention, and cleanup overhead. In API contexts, this defeats the purpose of synchronous rendering.
**Fix**: Use `imagepng($canvas)` or `imagejpeg($canvas)` directly to output buffers. Capture output with `ob_start()` and `ob_get_clean()` if returning binary data in HTTP responses. Reserve `renderToFile()` for batch jobs, PDF assembly, or persistent storage.

## Production Bundle

### Action Checklist
- [ ] Verify PHP version: Ensure runtime is PHP 8.3 or newer. Older versions lack required ZVAL structures and GD improvements.
- [ ] Confirm GD availability: Run `php -m | grep gd`. Install `php8.3-gd` or equivalent if missing.
- [ ] Configure extension loading: Add `extension=fastchart.so` to `php.ini` or `conf.d/`. Verify load order matches GD.
- [ ] Set font paths: Define absolute paths to TrueType fonts in environment variables or config. Test with `imagettfbbox()`.
- [ ] Benchmark rendering: Run `php docs/bench/bench.php` against your dataset size. Validate latency stays under 100ms at target resolution.
- [ ] Implement memory limits: Set `memory_limit` appropriately for batch jobs. Use `gc_collect_cycles()` in long-running workers.
- [ ] Add fallback rendering: Gracefully degrade to simplified charts or placeholder images if GD or extension fails to load.
- [ ] Document API contracts: Specify output formats, resolution limits, and ECC levels in internal documentation to prevent consumer mismatches.

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Real-time API dashboard tiles | Native PHP Extension | Synchronous, <100ms latency, no sidecar | Low (single .so) |
| Batch PDF report generation | Native PHP Extension + `renderToFile` | Predictable memory, file persistence | Low-Medium (disk I/O) |
| Complex interactive charts (user-driven) | Client-side JS (Chart.js/D3) | Browser handles interactivity, reduces server load | Medium (frontend bundle) |
| Legacy PHP 7.4 environment | Pure PHP GD wrapper or upgrade | Extension requires PHP 8.3+ | High (upgrade effort) |
| High-volume label printing | Native PHP Extension + QR/Barcode | C-level speed, quiet zone compliance | Low (CPU bound) |
| Multi-format export (SVG/PDF native) | External microservice (Python/Node) | GD lacks vector export, requires specialized libs | High (infrastructure) |

### Configuration Template

**php.ini / conf.d/20-fastchart.ini**
```ini
; Ensure GD loads first (handled internally by ZEND_MOD_REQUIRED, but explicit ordering helps)
extension=gd.so
extension=fastchart.so

; Optional: Increase memory for batch rendering jobs
memory_limit = 512M

; Optional: Disable output buffering for direct binary responses
output_buffering = Off

Dockerfile Snippet

FROM php:8.3-fpm

RUN apt-get update && apt-get install -y \
    libgd-dev \
    libfreetype6-dev \
    libjpeg62-turbo-dev \
    libpng-dev \
    libwebp-dev \
    libavif-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp --with-avif \
    && docker-php-ext-install gd

# Install pie package manager
RUN curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
RUN composer global require php/pie

# Install fastchart extension
RUN pie install iliaal/fastchart

# Verify installation
RUN php -m | grep -E 'gd|fastchart'

Quick Start Guide

1. Install the extension: Run pie install iliaal/fastchart or compile from source using phpize && ./configure --enable-fastchart && make -j && sudo make install.
2. Enable in PHP: Add extension=fastchart.so to your php.ini or conf.d/ directory. Restart PHP-FPM or CLI environment.
3. Verify dependencies: Execute php -m | grep -E 'gd|fastchart'. Both modules must appear. If fastchart fails to load, check GD installation and PHP version.
4. Render a test chart: Create a PHP script with new FastChart\LineChart(800, 600)->setSeries([['data' => [10, 25, 18, 40, 32]]])->renderToFile('/tmp/test.png');. Run php script.php and verify /tmp/test.png exists.
5. Integrate into workflow: Replace existing Puppeteer or pure-PHP rendering calls with the fluent API. Use draw($canvas) for compositing, renderToFile() for persistence, and direct GD output functions for API responses.