Merge pull request #10 from Intervention/feature/frame-block

Version 4

.github/ISSUE_TEMPLATE/feature_request.md

@@ -7,14 +7,8 @@ assignees: ''
 
 ---
 
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
-
-**Describe the solution you'd like**
+**Describe the feature you'd like**
 A clear and concise description of what you want to happen.
 
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
-**Additional context**
-Add any other context or screenshots about the feature request here.
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

.github/workflows/build.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: ['8.0', '8.1', '8.2']
+        php: ['8.1', '8.2', '8.3']
     name: Testing on PHP ${{ matrix.php }}
     steps:
       - name: Checkout

Dockerfile

@@ -1,4 +1,4 @@
-FROM php:8-cli
+FROM php:8.1-cli
 
 RUN apt update \
         && apt install -y \

README.md

@@ -5,9 +5,21 @@
 ![build](https://github.com/Intervention/gif/actions/workflows/build.yml/badge.svg)
 [![Monthly Downloads](https://img.shields.io/packagist/dm/intervention/gif.svg)](https://packagist.org/packages/intervention/gif/stats)
 
+Intervention GIF is a PHP encoder and decoder for the GIF image format that
+does not depend on any image processing extension. 
+
+Only the special `Splitter::class` class divides the data stream of an animated
+GIF into individual `GDImage` objects for each frame and is therefore dependent
+on the GD library.
+
+The library is the main component of [Intervention
+Image](https://github.com/Intervention/image) for processing animated GIF files
+with the GD library, but also works independently.
+
 ## Installation
 
-You can install this package easily with [Composer](https://getcomposer.org/). Just require the package with the following command:
+You can easily install this package using [Composer](https://getcomposer.org).
+Just request the package with the following command:
 
 ```bash
 composer require intervention/gif
@@ -21,7 +33,7 @@ composer require intervention/gif
 use Intervention\Gif\Decoder;
 
 // Decode filepath to Intervention\Gif\GifDataStream::class
-$gif = Decoder::decode('/images/animation.gif');
+$gif = Decoder::decode('images/animation.gif');
 
 // Decoder can also handle binary content directly
 $gif = Decoder::decode($contents);
@@ -34,28 +46,23 @@ Use the Builder class to create a new GIF image.
 ```php
 use Intervention\Gif\Builder;
 
-// create an empty canvas
-// 
-$width = 32;
-$height = 32;
-$loops = 0; // 0 for unlimited repetitions
-
-// create new gif with width/height and optional
-// number of repetitions of animation
-$gif = Builder::canvas($width, $height, $loops);
+// create new gif canvas
+$gif = Builder::canvas(width: 32, height: 32);
 
 // add animation frames to canvas
-// 
 $delay = .25; // delay in seconds after next frame is displayed
 $left = 0; // position offset (left)
 $top = 0; // position offset (top)
 
 // add animation frames with optional delay in seconds
 // and optional position offset for each frame
-$gif->addFrame('/images/frame01.gif', $delay, $left, $top);
-$gif->addFrame('/images/frame02.gif', $delay, $left);
-$gif->addFrame('/images/frame03.gif', $delay);
-$gif->addFrame('/images/frame04.gif');
+$gif->addFrame('images/frame01.gif', $delay, $left, $top);
+$gif->addFrame('images/frame02.gif', $delay, $left);
+$gif->addFrame('images/frame03.gif', $delay);
+$gif->addFrame('images/frame04.gif');
+
+// set loop count; 0 for infinite looping
+$gif->setLoops(12);
 
 // encode
 $data = $gif->encode();
@@ -64,7 +71,7 @@ $data = $gif->encode();
 
 ## Requirements
 
-- PHP >= 8.0
+- PHP >= 8.1
 
 ## Development & Testing
 
@@ -86,4 +93,4 @@ docker-compose run --rm --build analysis
 
 Intervention GIF is licensed under the [MIT License](http://opensource.org/licenses/MIT).
 
-Copyright 2020 [Oliver Vogel](http://intervention.io/)
+Copyright 2024 [Oliver Vogel](http://intervention.io/)

composer.json

@@ -12,7 +12,7 @@
         }
     ],
     "require": {
-        "php": "^8.0"
+        "php": "^8.1"
     },
     "require-dev": {
         "phpunit/phpunit": "^9",

src/AbstractEntity.php

@@ -22,4 +22,14 @@ public static function getShortClassname(): string
     {
         return (new ReflectionClass(get_called_class()))->getShortName();
     }
+
+    /**
+     * Cast object to string
+     *
+     * @return string
+     */
+    public function __toString(): string
+    {
+        return $this->encode();
+    }
 }

src/ApplicationExtension.php → src/Blocks/ApplicationExtension.php

@@ -1,11 +1,10 @@
 <?php
 
-namespace Intervention\Gif;
+namespace Intervention\Gif\Blocks;
 
-use Intervention\Gif\Contracts\SpecialPurposeBlock;
-use Intervention\Gif\DataSubBlock;
+use Intervention\Gif\AbstractExtension;
 
-class ApplicationExtension extends AbstractExtension implements SpecialPurposeBlock
+class ApplicationExtension extends AbstractExtension
 {
     public const LABEL = "\xFF";
 
@@ -14,14 +13,14 @@ class ApplicationExtension extends AbstractExtension implements SpecialPurposeBl
      *
      * @var string
      */
-    protected $application = '';
+    protected string $application = '';
 
     /**
      * Data Sub Blocks
      *
      * @var array
      */
-    protected $blocks = [];
+    protected array $blocks = [];
 
     public function getBlockSize(): int
     {

src/Color.php → src/Blocks/Color.php

@@ -1,42 +1,23 @@
 <?php
 
-namespace Intervention\Gif;
+namespace Intervention\Gif\Blocks;
+
+use Intervention\Gif\AbstractEntity;
 
 class Color extends AbstractEntity
 {
-    /**
-     * Red value
-     *
-     * @var int
-     */
-    protected $r;
-
-    /**
-     * Green value
-     *
-     * @var int
-     */
-    protected $g;
-
-    /**
-     * Blue value
-     *
-     * @var int
-     */
-    protected $b;
-
     /**
      * Create new instance
      *
      * @param int $r
      * @param int $g
      * @param int $b
      */
-    public function __construct(int $r = 0, int $g = 0, int $b = 0)
-    {
-        $this->r = $r;
-        $this->g = $g;
-        $this->b = $b;
+    public function __construct(
+        protected int $r = 0,
+        protected int $g = 0,
+        protected int $b = 0
+    ) {
     }
 
     /**

src/ColorTable.php → src/Blocks/ColorTable.php

@@ -1,24 +1,19 @@
 <?php
 
-namespace Intervention\Gif;
+namespace Intervention\Gif\Blocks;
+
+use Intervention\Gif\AbstractEntity;
 
 class ColorTable extends AbstractEntity
 {
-    /**
-     * Array of colors in table
-     *
-     * @var array
-     */
-    protected $colors = [];
-
     /**
      * Create new instance
      *
      * @param array $colors
+     * @return void
      */
-    public function __construct(array $colors = [])
+    public function __construct(protected array $colors = [])
     {
-        $this->setColors($colors);
     }
 
     /**
@@ -85,9 +80,9 @@ public function countColors(): int
     /**
      * Determine if any colors are present on the current table
      *
-     * @return boolean
+     * @return bool
      */
-    public function hasColors()
+    public function hasColors(): bool
     {
         return $this->countColors() >= 1;
     }

src/Blocks/CommentExtension.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Intervention\Gif\Blocks;
+
+use Intervention\Gif\AbstractExtension;
+
+class CommentExtension extends AbstractExtension
+{
+    public const LABEL = "\xFE";
+
+    /**
+     * Comment blocks
+     *
+     * @var array
+     */
+    protected array $comments = [];
+
+    /**
+     * Get all or one comment
+     *
+     * @return mixed
+     */
+    public function getComments()
+    {
+        return $this->comments;
+    }
+
+    /**
+     * Get one comment by key
+     *
+     * @param  int $key
+     * @return mixed
+     */
+    public function getComment(int $key): mixed
+    {
+        return array_key_exists($key, $this->comments) ? $this->comments[$key] : null;
+    }
+
+    /**
+     * Set comment text
+     *
+     * @param string $value
+     */
+    public function addComment(string $value): self
+    {
+        $this->comments[] = $value;
+
+        return $this;
+    }
+}

src/DataSubBlock.php → src/Blocks/DataSubBlock.php

@@ -1,17 +1,14 @@
 <?php
 
-namespace Intervention\Gif;
+namespace Intervention\Gif\Blocks;
 
-use Intervention\Gif\Exception\FormatException;
+use Intervention\Gif\AbstractEntity;
+use Intervention\Gif\Exceptions\FormatException;
 
 class DataSubBlock extends AbstractEntity
 {
-    protected $value;
-
-    public function __construct(string $value)
+    public function __construct(protected string $value)
     {
-        $this->value = $value;
-
         if ($this->getSize() > 255) {
             throw new FormatException(
                 'Data Sub-Block can not have a block size larger than 255 bytes.'