Gfx Php Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer (updated for v0.6 compatibility):

   composer require mike42/gfx-php:^0.6
   

   Laravel handles autoloading automatically.

2. First Use Case: Drawing a Simple Image Create a basic image with text or shapes (unchanged):

   use Mike42\Gfx\Gfx;
   
   $image = Gfx::create(200, 100);
   $image->fill(255, 255, 255); // White background
   $image->text('Hello, Laravel!', 10, 10, 0, 0, 0); // Black text
   $image->save('output.png');
   

3. New Feature: Reading BMP Files Load existing BMP images for editing or analysis:

   $bmpImage = Gfx::load('input.bmp');
   $bmpImage->save('output_converted.png'); // Convert BMP to PNG
   

4. Where to Look First

   • Documentation: Check the updated docs/ folder for BMP format specifics.
   • Source Code: Browse src/Mike42/Gfx/GfxImage.php for load() method updates.
   • Examples: Look for new test cases in tests/ (e.g., BmpTest.php).

Implementation Patterns

Core Workflows

1. Image Generation (Unchanged)

   • Use Gfx::create(width, height) for new canvases.
   • Chain methods like fill(), rect(), or text().

2. BMP File Handling (New)

   • Load BMPs: Use Gfx::load('path/to/file.bmp') to read BMPs (supports 8/16/24/32-bit, RLE compression, etc.).

     $bmp = Gfx::load('scan.bmp');
     $bmp->save('scan_converted.png'); // Auto-converts to PNG
     

   • Metadata Access: Extract BMP properties (e.g., dimensions, color depth) before processing:

     $bmp = Gfx::load('image.bmp');
     $width = $bmp->getWidth();
     $height = $bmp->getHeight();
     $bitsPerPixel = $bmp->getBitsPerPixel(); // e.g., 24
     

   • Batch Conversion: Process multiple BMPs (e.g., from uploads):

     foreach (Storage::files('bmp_uploads') as $path) {
         $image = Gfx::load($path);
         $image->save(str_replace('bmp', 'png', $path));
     }
     

3. Dynamic Content (Unchanged)

   • Generate images on-the-fly (e.g., for notifications or charts).

4. Laravel Integration (Updated)

   • Storage: Save converted BMPs alongside other images:

     $bmp = Gfx::load($request->file('bmp')->path());
     Storage::disk('public')->put('converted/' . $request->filename . '.png', $bmp->getImage());
     

   • Validation: Validate BMP uploads before processing:

     $request->validate([
         'bmp' => 'required|mimes:bmp',
     ]);
     

5. Font Handling (Unchanged)

   • Load custom fonts with GfxFont::load() for text rendering.

Gotchas and Tips

Pitfalls

1. BMP Format Quirks (New)

   • Issue: BMPs may use non-standard color spaces (e.g., 16-bit grayscale) or compression (e.g., RLE). The package handles most cases, but edge formats might fail silently.
   • Fix: Check $image->getBitsPerPixel() and log unsupported formats:

     if ($image->getBitsPerPixel() !== 24 && $image->getBitsPerPixel() !== 32) {
         Log::warning("Unsupported BMP format: {$image->getBitsPerPixel()} bits");
     }
     

   • Issue: BMPs lack built-in transparency. Alpha channels (if present) are converted to opaque during save().
   • Fix: Pre-process alpha channels if needed (e.g., using imagealphablending() in PHP’s GD).

2. Font Paths (Unchanged)

   • Issue: GfxFont::load() fails with incorrect paths.
   • Fix: Use absolute paths (e.g., storage_path('fonts/arial.ttf')).

3. Memory Limits (Updated)

   • Issue: Large BMPs (e.g., 32-bit 4K) may exceed PHP’s memory_limit.
   • Fix: Downsample BMPs before processing:

     $bmp = Gfx::load('large.bmp');
     $bmp->resize(1920, 1080); // Downsample to HD
     

4. Output Formatting (Unchanged)

   • Issue: Forgetting Content-Type headers for BMP outputs (though BMP is rarely served directly).
   • Fix: Always specify headers for converted formats (e.g., PNG/JPG):

     return response($image->getImage(), 200, ['Content-Type' => 'image/png']);
     

5. Color Values (Unchanged)

   • Issue: BMPs may use non-RGB color spaces (e.g., 16-bit grayscale).
   • Fix: Convert to RGB explicitly if needed:

     $rgb = $bmp->getPixelColor(10, 10); // Returns RGB integer
     

Debugging Tips

1. BMP Metadata Dump BMP properties to diagnose issues:

   $bmp = Gfx::load('problem.bmp');
   dd([
       'width' => $bmp->getWidth(),
       'height' => $bmp->getHeight(),
       'bits' => $bmp->getBitsPerPixel(),
       'compression' => $bmp->getCompression(),
   ]);
   

2. Fallback for Unsupported BMPs Gracefully handle unsupported formats:

   try {
       $image = Gfx::load('file.bmp');
   } catch (\Exception $e) {
       return response()->view('errors.bmp_unsupported');
   }
   

3. Performance Profiling Benchmark BMP loading for large files:

   $start = microtime(true);
   $bmp = Gfx::load('large.bmp');
   Log::info("BMP load time: " . (microtime(true) - $start) . "s");
   

Extension Points

1. BMP-Specific Filters (New) Extend GfxImage to add BMP-aware filters (e.g., RLE decompression):

   class BmpFilter extends GfxImage {
       public function decompressRLE() {
           // Custom logic for RLE BMPs
       }
   }
   

2. Format Auto-Detection Create a helper to detect and load BMPs/PNGs/JPEGs dynamically:

   function loadImage($path) {
       $ext = strtolower(pathinfo($path, PATHINFO_EXTENSION));
       return $ext === 'bmp'
           ? Gfx::load($path)
           : imagecreatefromstring(file_get_contents($path));
   }
   

3. Event Listeners (Unchanged) Trigger events for BMP conversions (e.g., bmp.converted):

   event(new BmpConverted($bmp, $outputPath));
   

4. Testing BMP Support Mock BMP loading in tests:

   $mockBmp = Mockery::mock('Mike42\Gfx\GfxImage');
   $mockBmp->shouldReceive('getWidth')->andReturn(800);
   $mockBmp->shouldReceive('getImage')->andReturn(file_get_contents('test.png'));