Merge pull request #5 from pboivin/feat/render-config

Add render options configuration

Author: pboivin

.gitignore

@@ -2,7 +2,7 @@
 *.swp
 
 /__tmp__
-/tests/fixtures/__cache__
+/tests/Fixtures/__cache__
 /vendor
 /composer.lock
 /.php_cs.cache

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Release Notes
 
+## [v1.2.0](https://github.com/pboivin/flou/compare/v1.1.0...v1.2.0) - 2022-08-24
+
+#### Added
+
+- Accept render options as array (`ImageFactory`)
+- Add missing setter for padding element CSS class (`ImgRenderable`)
+
+#### Changed
+
+- Ensure base64 LQIP is usable with wrapper option (`ImgRenderable`)
+
+#### Chores
+
+- Document various configuration options
+
+
 ## [v1.1.0](https://github.com/pboivin/flou/compare/v1.0.1...v1.1.0) - 2022-08-10
 
 #### Added

README.md

@@ -91,12 +91,24 @@ $flou = new ImageFactory([
 ]);
 ```
 
+
+#### Configuration
+
 The required options are:
 
-- `sourcePath`: The full path to the source images.
-- `cachePath`: The full path where Glide will store the image transformations.
-- `sourceUrlBase`: The base URL for the source images.
-- `cacheUrlBase`:  The base URL for the transformed images.
+| Name | Type | Description |
+|---|---|---|
+| `sourcePath` | string | The full path to the source images. |
+| `cachePath` | string | The full path where Glide will store the image transformations. |
+| `sourceUrlBase` | string | The base URL for the source images. |
+| `cacheUrlBase` | string | The base URL for the transformed images. |
+
+Other options:
+
+| Name | Type | Description |
+|---|---|---|
+| `glideParams` | array | [Default Glide parameters for LQIP elements.](#default-glide-parameters) |
+| `renderOptions` | array | [Default render options for all images.](#default-render-options) |
 
 
 #### Framework Integration
@@ -351,6 +363,39 @@ The `ImageRender` object can be configured to optimize the HTML output:
     <br>
 
 
+#### Default render options
+
+You can customize the default render options for all images in the `ImageFactory` configuration:
+
+```php
+$flou = new ImageFactory([
+    // ...
+    'renderOptions' => [
+        'aspectRatio' => 16 / 9,
+        'wrapper' => true,
+        'base64Lqip' => true,
+        // ...
+    ],
+]);
+```
+
+<details>
+<summary>See Available Options</summary>
+
+| Name | Type | Description |
+|---|---|---|
+| `baseClass` | string | CSS class for `img` element. Default: `'lazyload'` |
+| `wrapperClass` | string | CSS class for wrapper element. Default: `'lazyload-wrapper'` |
+| `lqipClass` | string | CSS class for LQIP element. Default: `'lazyload-lqip'` |
+| `paddingClass` | string | CSS class for padding-specific wrapper element. Default: `'lazyload-padding'` |
+| `aspectRatio` | boolean or number | Use aspect ratio. Default: `false` |
+| `paddingTop` | boolean or number | Use padding-top workaround. Default: `false` |
+| `wrapper` | boolean | Use wrapper element. Default: `false` |
+| `base64Lqip` | boolean | Use Base64 LQIP value. Default: `false` |
+</details>
+<br>
+
+
 #### Noscript variation
 
 Use the `noScript()` method to render an `img` element without any lazy loading behavior:

src/Image.php

@@ -4,6 +4,10 @@
 
 class Image
 {
+    protected $renderClass = ImageRender::class;
+
+    protected $renderOptions = [];
+
     public function __construct(protected ImageFile $source, protected ImageFile $cached)
     {
     }
@@ -18,9 +22,19 @@ public function cached(): ImageFile
         return $this->cached;
     }
 
+    public function setRenderClass(string $cls): void
+    {
+        $this->renderClass = $cls;
+    }
+
+    public function setRenderOptions(array $options): void
+    {
+        $this->renderOptions = $options;
+    }
+
     public function render(): ImageRender
     {
-        return new ImageRender($this);
+        return new ($this->renderClass)($this, $this->renderOptions);
     }
 
     public function toArray(): array

src/ImageFactory.php

@@ -24,6 +24,8 @@ class ImageFactory
 
     protected $inspector;
 
+    protected $renderOptions;
+
     final public function __construct(array $config = [])
     {
         if ($config) {
@@ -171,6 +173,11 @@ public function setInspector(ImageFileInspector $inspector): self
         return $this;
     }
 
+    public function setRenderOptions(array $options): void
+    {
+        $this->renderOptions = $options;
+    }
+
     public function image(string $sourceFileName, ?array $glideParams = null): Image
     {
         $glideParams ??= $this->glideParams();
@@ -179,15 +186,27 @@ public function image(string $sourceFileName, ?array $glideParams = null): Image
 
         $cachedFileName = $server->makeImage($sourceFileName, $glideParams);
 
-        return new Image(
+        $image = new Image(
             $this->sourceImageFile($sourceFileName),
             $this->cachedImageFile($cachedFileName)
         );
+
+        if ($this->renderOptions) {
+            $image->setRenderOptions($this->renderOptions);
+        }
+
+        return $image;
     }
 
     public function imageSet(array $config): ImageSet
     {
-        return new ImageSet($config, $this);
+        $set = new ImageSet($config, $this);
+
+        if ($this->renderOptions) {
+            $set->setRenderOptions($this->renderOptions);
+        }
+
+        return $set;
     }
 
     public function sourceImageFile(string $fileName): ImageFile

src/ImageRender.php

@@ -4,8 +4,11 @@
 
 class ImageRender extends ImgRenderable
 {
-    public function __construct(protected Image $image)
+    public function __construct(protected Image $image, protected array $config = [])
     {
+        if ($config) {
+            $this->acceptRenderConfig($config);
+        }
     }
 
     public function main(): ImageFile

src/ImageSet.php

@@ -8,6 +8,10 @@ class ImageSet
 {
     public const DEFAULT_SIZES_VALUE = '100vw';
 
+    protected $renderClass = ImageSetRender::class;
+
+    protected $renderOptions = [];
+
     protected $image;
 
     protected $sizes;
@@ -110,8 +114,18 @@ public function toArray(): array
         ];
     }
 
+    public function setRenderClass(string $cls): void
+    {
+        $this->renderClass = $cls;
+    }
+
+    public function setRenderOptions(array $options): void
+    {
+        $this->renderOptions = $options;
+    }
+
     public function render(): ImageSetRender
     {
-        return new ImageSetRender($this);
+        return new ($this->renderClass)($this, $this->renderOptions);
     }
 }

src/ImageSetRender.php

@@ -6,9 +6,13 @@ class ImageSetRender extends ImgRenderable
 {
     protected $data;
 
-    public function __construct(protected ImageSet $imageSet)
+    public function __construct(protected ImageSet $imageSet, protected array $config = [])
     {
         $this->data = $this->imageSet->data();
+
+        if ($config) {
+            $this->acceptRenderConfig($config);
+        }
     }
 
     public function main(): ImageFile

src/ImgRenderable.php

@@ -2,6 +2,7 @@
 
 namespace Pboivin\Flou;
 
+use InvalidArgumentException;
 use Stringable;
 
 abstract class ImgRenderable implements Stringable
@@ -22,32 +23,53 @@ abstract class ImgRenderable implements Stringable
 
     protected $wrapper = false;
 
+    protected $base64Lqip = false;
+
+    /* Internal */
     protected $includeLqip = true;
 
-    protected $base64Lqip = false;
+    protected function acceptRenderConfig(array $config): void
+    {
+        foreach ($config as $key => $value) {
+            if (method_exists($this, $method = "set{$key}")) {
+                $this->$method($value);
+            } elseif (method_exists($this, $method = "use{$key}")) {
+                $this->$method($value);
+            } else {
+                throw new InvalidArgumentException("Invalid option '$key'.");
+            }
+        }
+    }
 
     public function __toString(): string
     {
         return $this->img();
     }
 
-    public function setBaseClass(string $cls): self
+    public function setBaseClass(string $cssClass): self
     {
-        $this->baseClass = $cls;
+        $this->baseClass = $cssClass;
 
         return $this;
     }
 
-    public function setWrapperClass(string $cls): self
+    public function setWrapperClass(string $cssClass): self
     {
-        $this->wrapperClass = $cls;
+        $this->wrapperClass = $cssClass;
 
         return $this;
     }
 
-    public function setLqipClass(string $cls): self
+    public function setLqipClass(string $cssClass): self
     {
-        $this->lqipClass = $cls;
+        $this->lqipClass = $cssClass;
+
+        return $this;
+    }
+
+    public function setPaddingClass(string $cssClass): self
+    {
+        $this->paddingClass = $cssClass;
 
         return $this;
     }
@@ -59,18 +81,24 @@ public function useWrapper(bool $value = true): self
         return $this;
     }
 
-    public function useAspectRatio(?float $value = null): self
+    public function useAspectRatio(mixed $value = true): self
     {
-        $this->aspectRatio = is_null($value) ? $this->main()->ratio() : $value;
+        if ($value === true) {
+            $this->aspectRatio = $this->main()->ratio();
+        } elseif ($value === false) {
+            $this->aspectRatio = false;
+        } else {
+            $this->aspectRatio = $value;
+        }
 
         return $this;
     }
 
-    public function usePaddingTop(?float $value = null): self
+    public function usePaddingTop(mixed $value = true): self
     {
         $this->useAspectRatio($value);
 
-        $this->paddingTop = true;
+        $this->paddingTop = !!$value;
 
         return $this;
     }
@@ -182,7 +210,7 @@ protected function handleWrapper(string $input): string
                     $this->includeLqip
                         ? $this->htmlTag('img', [
                             'class' => $this->lqipClass,
-                            'src' => $this->lqip()->url(),
+                            'src' => $this->lqipUrl(),
                         ])
                         : '',
                 ])

tests/Fixtures/TestImageRender.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Pboivin\Flou\Tests\Fixtures;
+
+use Pboivin\Flou\ImageRender;
+
+class TestImageRender extends ImageRender
+{
+}