Publish an example

CHANGES.txt

@@ -0,0 +1,22 @@
+TODO:
+
+! Allow image dirs within the input list (array), too, not only instead of it.
+
+! In local testing I had a strange issue with by-frame delays: the first image eats
+  up the first two delays, and is shown for the sum of those two numbers... :-o
+  -> And I seem to be unable to reproduce it now! :-o
+
+* Warn about explicit sorting if per-frame delays are specified for a dir source?
+
+* Sync the index.php (demo & quickstart frontend) with the examples in README.md 
+  AND ALSO THE ONE AT SO!
+
+* To avoid unwanted "in-band" PHP output, I should probably disable display_errors()
+  in the whole module (restoring it on normal exit)...
+
+
+------------------------------------------------------------------------------------
+DONE:
+
+-> Release notes: https://github.com/lunakid/AnimGif/releases/
+-> See also the GitHub commit history: https://github.com/lunakid/AnimGif/commits/

README.md

@@ -1,67 +1,86 @@
-# ================================
-# GifCreator
-# ================================
+> *NOTE: This is a fork of [Clément Guillemain](https://github.com/Sybio)'s nice [GifCreator class](https://github.com/Sybio/GifCreator), with some API changes (class rename, new & updated methods, more flexible (and robust) parameter handling etc.), better error handling, several small corrections, code cosmetics & other improvements scattered all across.*
 
-GifCreator is a PHP class to create animated GIF from multiple images
+### About 
 
-### For what ?
+AnimGif is a PHP class to create animated GIFs -- just list the source images (in various forms), and that's it!
 
-This class helps you to create an animated GIF image: give multiple images and their duration and that's it !
 
 ### Usage
 
-**1 - Creation:**
+**1. Inputs:**
 
 ```php
-// Create an array containing file paths, resource var (initialized with imagecreatefromXXX), 
-// image URLs or even binary code from image files.
-// All sorted in order to appear.
+// Use an array containing file paths, resource vars (initialized with imagecreatefromXXX), 
+// image URLs or binary image data.
 $frames = array(
-    imagecreatefrompng("/../images/pic1.png"), // Resource var
-    "/../images/pic2.png", // Image file path
-    file_get_contents("/../images/pic3.jpg"), // Binary source code
-    'http://thisisafakedomain.com/images/pic4.jpg', // URL
+    imagecreatefrompng("/../images/pic1.png"),      // resource var
+    "/../images/pic2.png",                          // image file path
+    file_get_contents("/../images/pic3.jpg"),       // image binary data
+    "http://thisisafakedomain.com/images/pic4.jpg", // URL
 );
 
-// Create an array containing the duration (in millisecond) of each frames (in order too)
-$durations = array(40, 80, 40, 20);
+// Or: load images from a dir (sorted, skipping .files):
+//$frames = "../images";
 
-// Initialize and create the GIF !
-$gc = new GifCreator();
-$gc->create($frames, $durations, 5);
+// Optionally: set different durations (in 1/100s units) for each frame
+$durations = array(20, 30, 10, 10);
+
+// Or: you can leave off repeated values from the end:
+//$durations = array(20, 30, 10); // use 10 for the rest
+// Or: use 'null' anywhere to re-apply the previous delay:
+//$durations = array(250, null, null, 500);
+```
+
+**2. Create the GIF:**
+
+``` php
+$anim = new GifCreator\AnimGif();
+$anim->create($frames, $durations);
+
+// Or: using the default 100ms even delay:
+//$anim->create($frames);
+
+// Or: loop 5 times, then stop:
+//$anim->create($frames, $durations, 5); // default: infinite looping
 ```
-The 3rd parameter of create() method allows you to choose the number of loop of your animated gif before it stops.
-In the previous example, I chose 5 loops. Set 0 (zero) to get an infinite loop.
 
-**2 - Get the result:**
+**3. Get/use the result:**
 
 You can now get the animated GIF binary:
 
 ```php
-$gifBinary = $gc->getGif();
+$gif = $anim->get();
 ```
 
-Then you can show it in the navigator:
+...and e.g. send it directly to the browser:
 
 ```php
-header('Content-type: image/gif');
-header('Content-Disposition: filename="butterfly.gif"');
-echo $gifBinary;
+header("Content-type: image/gif");
+echo $gif;
 exit;
 ```
 
-Or save it in a folder as a GIF:
+Or just save it to a file:
 
 ```php
-file_put_contents('/myfolder/animated_picture.gif', $gifBinary);
+$anim->save("animated.gif");
 ```
 
+
 ### Behavior
 
-- The transparency is based on the first given frame. It will be saved only if you give multiple frames with same transparent background.
-- The dimensions of the generated GIF are based on the first frame. If you need to resize your frames to get the same dimension, you can use 
-this class: https://github.com/Sybio/ImageWorkshop
+- Transparency is based on the first frame. [!!NOT VERIFIED: "It will be saved only if you give multiple frames with the same transparent background"]
+- The dimensions of the generated GIF are based on the first frame, too. If you need to resize your images to get the same dimensions, you can use this class: https://github.com/Sybio/ImageWorkshop.
+
+
+### Dependencies
+
+* PHP 5.3 (for namespace support & whatnot; noone still shamelessly uses PHP < 5.3, right?!)
+* GD (`imagecreatefromstring`, `imagegif`, `imagecolortransparent`)
+
 
-### About
+### Credits
 
-The class reuses some part of code of "GIFEncoder.class.php" by László Zsidi (thanks to him).
+* László Zsidi: All the tough parts come from his [GIFEncoder.class.php](http://www.phpclasses.org/package/3163) (also found [here, in a Gist](https://gist.github.com/allometry/1438842)). Thanks, Laci!
+* Clément Guillemain: for the very handy, redesigned (& "classified") API, extensions and nice docs!
+* Matthew Flickinger: for his amazing, unbeatable [GIF format dissection page](http://www.matthewflickinger.com/lab/whatsinagif/bits_and_bytes.asp).

composer.json

@@ -1,15 +1,20 @@
 {
-    "name": "sybio/gif-creator",
+    "name": "lunakid/anim-gif",
     "type": "library",
-    "description": "PHP class that creates animated GIF from multiple images",
+    "description": "PHP class to create an animated GIF from multiple images",
     "keywords": ["gif", "animated", "creation", "encode", "PHP"],
-    "homepage": "https://github.com/Sybio/GifCreator",
+    "homepage": "https://github.com/lunakid/AnimGif",
     "license": "MIT",
     "authors": [
         {
             "name": "Clément Guillemain",
             "homepage": "http://clementguillemain.fr",
             "role": "Developer / Freelancer"
+        },
+        {
+            "name": "Szabolcs Szász",
+            "homepage": "http://github.com/lunakid",
+            "role": "Developer / Freelancer"
         }
     ],
     "require": {
@@ -18,4 +23,4 @@
     "autoload": {
         "psr-0": { "GifCreator": "src" }
     }
-}
+}