Pixel Art Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require appventus/pixel-art-bundle
   

   Ensure the bundle is enabled in config/bundles.php (Symfony 4.4+ auto-discovers it).

2. First Use Case: Add the Twig filter to a template:

   {{ "Hello"|pixelart|raw }}
   

   This renders "Hello" in a default pixel-art font. The |raw ensures the HTML output is not escaped.

3. Where to Look First:

   • Available Fonts (e.g., block, small, speed).
   • Bundle’s Resources/views/ for default templates (if extended).

Implementation Patterns

Core Workflows

1. Dynamic PixelArt Rendering: Use the filter with optional font parameter:

   {% for name in ["Laravel", "PHP"] %}
       {{ name|pixelart("speed")|raw }}
   {% endfor %}
   

   • Laravel Integration: Inject the Twig environment in a service/controller to dynamically generate pixel-art strings:

     $twig->render('{{ "Pixel"|pixelart("block")|raw }}');
     

2. Customizing Output:

   • Styling: Wrap the output in a <div> with CSS classes for alignment/scaling:

     <div class="pixel-art-container">
         {{ "Laravel"|pixelart("small")|raw }}
     </div>
     

   • Dynamic Fonts: Fetch available fonts programmatically:

     $fonts = $this->get('pixel_art.font_manager')->getAvailableFonts();
     

3. Reusable Components: Create a Twig macro for consistency:

   {% macro pixelText(text, font="default") %}
       <span class="pixel-font">{{ text|pixelart(font)|raw }}</span>
   {% endmacro %}
   

   Usage:

   {{ _self.pixelText("Dev", "speed") }}
   

4. API Responses: Return pixel-art as part of JSON responses (base64-encoded SVG):

   return response()->json([
       'message' => 'Pixelated!',
       'pixelArt' => base64_encode($twig->render('{{ "API"|pixelart("block")|raw }}'))
   ]);
   

Gotchas and Tips

Pitfalls

1. Font Availability:

   • The bundle ships with limited fonts. If a font (e.g., "custom") is not found, the filter silently falls back to default. Validate fonts dynamically:

     if (!$this->get('pixel_art.font_manager')->hasFont('custom')) {
         throw new \InvalidArgumentException("Font 'custom' not available.");
     }
     

2. Performance:

   • Pixel-art generation is CPU-intensive for long strings. Cache rendered output in Laravel:

     $cacheKey = "pixel_art_{$text}_{$font}";
     return Cache::remember($cacheKey, now()->addHours(1), function() use ($text, $font) {
         return $twig->render('{{ "'.$text.'"|pixelart("'.$font.'")|raw }}');
     });
     

3. Twig Auto-escaping: Always use |raw to prevent HTML escaping from breaking the pixel-art SVG.

4. Bundle Compatibility:

   • The bundle is Symfony-specific. For Laravel, use it via Symfony’s Twig integration or adapt the core logic (e.g., extract the PixelArt class and use it directly).

Debugging

• Check Font Paths: If fonts fail to load, verify the bundle’s Resources/public/fonts/ directory is symlinked or copied to public/:

  php bin/console assets:install
  

• Inspect SVG Output: Use browser dev tools to debug malformed pixel-art. Common issues:
  • Missing viewBox attributes in SVG.
  • Incorrect font character mappings (check fonts.md).

Extension Points

1. Add Custom Fonts:

   • Place new .ttf/.otf files in Resources/public/fonts/ and update the font manager:

     # config/packages/pixel_art.yaml
     pixel_art:
         fonts:
             - { name: "custom", path: "%kernel.project_dir%/public/fonts/custom.ttf" }
     

2. Modify Rendering Logic:

   • Override the PixelArt class (e.g., in app/PixelArt/PixelArt.php) to customize:
     • Character spacing.
     • Color schemes (extend getColor() method).
     • SVG attributes.

3. Laravel-Specific Adaptations:

   • For Laravel, create a facade to wrap the Twig filter:

     // app/Facades/PixelArt.php
     public static function make($text, $font = 'default') {
         return app('twig')->render('{{ "'.$text.'"|pixelart("'.$font.'")|raw }}');
     }
     

   • Use Laravel’s service provider to bind the bundle’s services:

     public function register() {
         $this->app->register(new \AppVentus\PixelArtBundle\AppVentusPixelArtBundle());
     }
     

Pro Tips

• Theming: Use CSS variables to theme pixel-art colors globally:

  .pixel-art-container svg {
      --pixel-color: #ff0000;
  }
  

• Responsive Design: Scale pixel-art with CSS:

  .pixel-art-container {
      transform: scale(1.5);
      transform-origin: 0 0;
  }
  

• Accessibility: Add ARIA labels to pixel-art containers for screen readers:

  <div class="pixel-art-container" aria-label="Pixel art text: Laravel">
      {{ "Laravel"|pixelart("speed")|raw }}
  </div>