Added note on how to make example. Made example finder scan all directories and be cached by redis.

Author: Danack

README.md

@@ -17,9 +17,61 @@ http://local.im6.phpimagick.com - explicitly use ImageMagick 6
 
 http://local.im7.phpimagick.com - explicitly use ImageMagick 7
 
-
 It will take a few minutes (or more) to come up, as it has to compile ImageMagick 6 and 7, and then Imagick. After the first run, these are cached, so should only take a few seconds.
 
-## PHPStorm stub file
+The site is built against the master branch of Imagick at https://github.com/imagick/imagick . As it takes a long time, by default it doesn't rebuild from scratch each time. To force a rebuild against the latest version of Imagick
+
+```
+runRebuildLocal.sh
+```
+
+containers/imagick_php_base_im7/install_imagemagick.sh
+containers/imagick_php_base_im6/install_imagemagick.sh
+
+
+## Adding examples
+
+There is a list of which examples still need to be added at [phpimagick.com/todo](https://phpimagick.com/todo).
+
+Here are some instructions on adding examples.
+
+### Text example
+
+A text example, is an example that has text as it's output, rather than an image e.g. Imagick::getImageMimeType has [an example added for it in this commit](https://github.com/Imagick/ImagickDemos/commit/9df6cef1051ab6fa90d1bf834a23d083bdf5ab79).
+
+The steps involved are:
+
+1. Add the example to appropriate list in src/example_list.php
+
+getImagickExamples(), getImagickDrawExamples(), getImagickKernelExamples(), getImagickPixelExamples(), getImagickPixelIteratorExamples(), getTutorialExamples()
+
+For each entry in the array, the key is the example name and value is the example controller and example function name. Although most of the time these are the same some examples re-use a controller + function, as there isn't much point duplicating code. e.g. for ImagickDraw 'popClipPath' => 'setClipPath',
+
+2. Create a controller
+
+Usually copying an existing one is a good idea.
+
+3. Mark the example code with a comment with the exact spelling like:
+
+```
+//Example Imagick::getImageMimeType
+    $imagick = new \Imagick($this->imageControl->getImagePath());
+
+    $output = 'Imagick::getImageMimeType result is: ';
+    $output .= $imagick->getImageMimeType();
+
+    return $output;
+//Example end
+```
+
+This makes the example code be picked up and shown on the webpage.
+
+
+
+### Standard image example
+
+TODO - write words...
+
+### Standard image example
 
-TODO - move the instructions to the Imagick extension...
+TODO - write words...

src/ImagickDemo/Controller/Page.php

@@ -50,7 +50,8 @@ public function renderExamplePageMoreSane(
         Control $control,
         Example $example,
         DocHelper $docHelper,
-        \ImagickDemo\Queue\ImagickTaskQueue $taskQueue
+        \ImagickDemo\Queue\ImagickTaskQueue $taskQueue,
+        \ImagickDemo\ExampleFinder\ExampleFinder $exampleFinder
     ) {
         return renderPageHtml(
             $categoryNav,
@@ -60,7 +61,8 @@ public function renderExamplePageMoreSane(
             $example,
             $docHelper,
             $varMap,
-            $taskQueue
+            $taskQueue,
+            $exampleFinder
         );
     }
 }

src/ImagickDemo/ExampleFinder/ExampleFinder.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ImagickDemo\ExampleFinder;
+
+use ImagickDemo\CodeExample;
+
+interface ExampleFinder
+{
+    /**
+     * @param string $category
+     * @param string $example
+     * @return CodeExample[]
+     */
+    public function findExamples(string $category, string $example);
+}

src/ImagickDemo/ExampleFinder/ExampleSourceFinder.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace ImagickDemo\ExampleFinder;
+
+use ImagickDemo\CodeExample;
+use ImagickDemo\ExampleExtractor;
+
+class ExampleSourceFinder implements ExampleFinder
+{
+    /**
+     * @var \SplFileInfo[]
+     */
+    private $directories;
+
+    function __construct() {
+        // TODO - scan all PHP files again.
+        $directory = new \RecursiveDirectoryIterator(__DIR__ . '/../../../src');
+        $iterator = new \RecursiveIteratorIterator($directory);
+        $this->directories = new \RegexIterator(
+            $iterator, '/^.+\.php$/i',
+            \RecursiveRegexIterator::GET_MATCH
+        );
+    }
+
+    /**
+     * @param string $category
+     * @param string $example
+     * @return CodeExample[]
+     */
+    public function findExamples(string $category, string $example)
+    {
+        $examples = [];
+
+        foreach ($this->directories as $directory) {
+            foreach ($directory as $filename) {
+                // open the file
+                $fileLines = file($filename);
+                if (!$fileLines) {
+                    throw new \Exception("Failed to open [" . $filename . "]");
+                }
+                $exampleExtractor = new ExampleExtractor($fileLines, $category, $example);
+                $found_examples = $exampleExtractor->getAllCodeExamples();
+                array_push($examples, ...$found_examples);
+            }
+        }
+
+        return $examples;
+    }
+}

src/ImagickDemo/ExampleFinder/RedisExampleFinder.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ImagickDemo\ExampleFinder;
+
+use ImagickDemo\CodeExample;
+use Predis\Client as RedisClient;
+
+class RedisExampleFinder implements ExampleFinder
+{
+    private ExampleSourceFinder $exampleSourceFinder;
+
+    public function __construct(private RedisClient $redis, private int $ttl)
+    {
+        $this->exampleSourceFinder = new ExampleSourceFinder();
+    }
+
+    /**
+     * @param CodeExample[]
+     */
+    private function examplesToString(array $examples): string
+    {
+        $arrays = [];
+        foreach ($examples as $example) {
+            $arrays[] = (array)$example;
+        }
+
+        return json_encode_safe($arrays);
+    }
+
+    /**
+     * @return CodeExample[]
+     */
+    private function examplesFromString(string $encoded)
+    {
+        $examples = [];
+
+        $array = json_decode_safe($encoded);
+        foreach ($array as $entry) {
+            $examples[] = new CodeExample(
+                $entry['category'],
+                $entry['function'],
+                $entry['lines'],
+                $entry['description'],
+                $entry['startLine']
+            );
+        }
+
+        return $examples;
+    }
+
+    public function findExamples(string $category, string $example)
+    {
+        $key = 'example_' . $category . '_' . $example;
+        $result = $this->redis->get($key);
+
+        if ($result === null) {
+            $examples = $this->exampleSourceFinder->findExamples($category, $example);
+            $string = $this->examplesToString($examples);
+            $this->redis->set($key, $string, 'EX', $this->ttl);
+            return $examples;
+        }
+
+        $examples = $this->examplesFromString($result);
+        return $examples;
+    }
+}

src/ImagickDemo/ExampleSourceFinder.php

@@ -5,6 +5,14 @@
 
 function getImagickDrawExamples()
 {
+    // key is the example name
+    // value is the example controller and example function name
+    //
+    // Although most of the time these are the same
+    // some examples re-use a controller + function, as there
+    // isn't much point duplicating code.
+    //
+    // e.g. for ImagickDraw 'popClipPath' => 'setClipPath',
     return [
         'affine' => 'affine',
         'arc' => 'arc',
@@ -71,6 +79,14 @@ function getImagickDrawExamples()
 
 function getImagickPixelExamples()
 {
+    // key is the example name
+    // value is the example controller and example function name
+    //
+    // Although most of the time these are the same
+    // some examples re-use a controller + function, as there
+    // isn't much point duplicating code.
+    //
+    // e.g. for ImagickDraw 'popClipPath' => 'setClipPath',
     return [
         'construct' => 'construct',
         'clear' => 'clear',
@@ -95,6 +111,14 @@ function getImagickPixelExamples()
 
 function getImagickPixelIteratorExamples()
 {
+    // key is the example name
+    // value is the example controller and example function name
+    //
+    // Although most of the time these are the same
+    // some examples re-use a controller + function, as there
+    // isn't much point duplicating code.
+    //
+    // e.g. for ImagickDraw 'popClipPath' => 'setClipPath',
     return [
         'clear' => 'clear',
         'construct' => 'construct',
@@ -114,6 +138,14 @@ function getImagickPixelIteratorExamples()
 
 function getImagickKernelExamples()
 {
+    // key is the example name
+    // value is the example controller and example function name
+    //
+    // Although most of the time these are the same
+    // some examples re-use a controller + function, as there
+    // isn't much point duplicating code.
+    //
+    // e.g. for ImagickDraw 'popClipPath' => 'setClipPath',
     return [
         'addKernel' => 'addKernel',
         'addUnityKernel' => 'addUnityKernel',
@@ -128,6 +160,14 @@ function getImagickKernelExamples()
 
 function getTutorialExamples()
 {
+    // key is the example name
+    // value is the example controller and example function name
+    //
+    // Although most of the time these are the same
+    // some examples re-use a controller + function, as there
+    // isn't much point duplicating code.
+    //
+    // e.g. for ImagickDraw 'popClipPath' => 'setClipPath',
     return [
         'backgroundMasking' => 'backgroundMasking',
         'composite' => 'composite',
@@ -163,6 +203,14 @@ function getTutorialExamples()
 
 function getImagickExamples()
 {
+    // key is the example name
+    // value is the example controller and example function name
+    //
+    // Although most of the time these are the same
+    // some examples re-use a controller + function, as there
+    // isn't much point duplicating code.
+    //
+    // e.g. for ImagickDraw 'popClipPath' => 'setClipPath',
     return [
         'adaptiveBlurImage' => 'adaptiveBlurImage',
         'adaptiveResizeImage' => 'adaptiveResizeImage',

src/example_list.php

@@ -211,4 +211,16 @@ function createTwigForSite(\Auryn\Injector $injector)
     }
 
     return $twig;
+}
+
+function createExampleFinder(
+    Predis\Client $redisClient,
+    Config $config
+) {
+    $cache_time = 60; // 1 minute
+    if ($config->isProductionEnv() === true) {
+        $cache_time = 10000000000; // more than 1 minute
+    }
+//  return new \ImagickDemo\ExampleFinder\ExampleSourceFinder();
+    return new \ImagickDemo\ExampleFinder\RedisExampleFinder($redisClient, $cache_time);
 }