Merge pull request #16 from samrap/0.3

v0.3.0 - First stable release

readme.md

@@ -210,6 +210,20 @@ The current supported functions for the `escape` method are:
 
 ---
 
+#### `Samrap\Acf\Fluent\Builder::shortcodes(void)`
+
+You may have a textarea or WYSIWYG field in which you wish to support shortcodes. You could pass the retreived value through the `do_shortcode` function, but with ACF Fluent there is a better way. The `shortcodes` method will instruct ACF Fluent to call the WordPress `do_shortcode` function on the retrieved value automatically:
+
+```php
+use Samrap\Acf\Acf;
+
+$content = Acf::field('wysiwyg')
+              ->shortcodes()
+              ->get();
+```
+
+If the field value is not a string, a `\Samrap\Acf\Exceptions\RunnerException` exception will be thrown.
+
 #### `Samrap\Acf\Fluent\Builder::raw(void)`
 
 When retrieving a field, ACF lets you specify whether or not to format the value from the database. ACF Fluent follows the plugin's convention by formatting the field by default. You may use the builder's `raw` method to retrieve the value from the database unformatted:

src/Acf.php

@@ -9,6 +9,20 @@
 
 class Acf
 {
+    /**
+     * The class' single instance.
+     *
+     * @var \Samrap\Acf\Acf
+     */
+    private static $instance;
+
+    /**
+     * The behavior instances.
+     *
+     * @var \Samrap\Acf\Behaviors\BehaviorInterface[]
+     */
+    private $behaviors = [];
+
     /**
      * Private constructor to prevent instantiation.
      *
@@ -19,6 +33,20 @@ private function __construct()
         //
     }
 
+    /**
+     * Get the single instance of this object.
+     *
+     * @return \Samrap\Acf\Acf
+     */
+    private static function getInstance()
+    {
+        if (! self::$instance) {
+            self::$instance = new self();
+        }
+
+        return self::$instance;
+    }
+
     /**
      * Return a new builder instance for a field call.
      *
@@ -28,7 +56,8 @@ private function __construct()
      */
     public static function field($name, $id = null)
     {
-        return static::getBuilder(FieldBehavior::class)
+        return self::getInstance()
+                     ->getBuilder(FieldBehavior::class)
                      ->field($name)
                      ->id($id);
     }
@@ -41,7 +70,9 @@ public static function field($name, $id = null)
      */
     public static function subField($name)
     {
-        return static::getBuilder(SubFieldBehavior::class)->field($name);
+        return self::getInstance()
+                     ->getBuilder(SubFieldBehavior::class)
+                     ->field($name);
     }
 
     /**
@@ -52,7 +83,8 @@ public static function subField($name)
      */
     public static function option($name)
     {
-        return static::getBuilder(FieldBehavior::class)
+        return self::getInstance()
+                     ->getBuilder(FieldBehavior::class)
                      ->field($name)
                      ->id('option');
     }
@@ -63,8 +95,13 @@ public static function option($name)
      * @param  string  $behavior
      * @return \Samrap\Acf\Fluent\Builder
      */
-    private static function getBuilder($behavior)
+    private function getBuilder($behavior)
     {
-        return new Builder(new Runner(new $behavior));
+        // Create a new behavior of the given type if one does not yet exist.
+        if (! isset($this->behaviors[$behavior])) {
+            $this->behaviors[$behavior] = new $behavior();
+        }
+
+        return new Builder(new Runner($this->behaviors[$behavior]));
     }
 }

src/Fluent/Builder.php

@@ -50,6 +50,13 @@ class Builder
     public $escape;
 
     /**
+     * Whether or not to do shortcodes.
+     *
+     * @var bool
+     */
+    public $shortcodes;
+
+    /*
      * Get the field raw (unformatted).
      *
      * @var bool
@@ -143,6 +150,16 @@ public function escape($func = 'esc_html')
     }
 
     /**
+     * Set the shortcodes component.
+     *
+     * @return \Samrap\Acf\Fluent\Builder
+     */
+    public function shortcodes()
+    {
+        $this->shortcodes = true;
+    }
+
+    /*
      * Set the raw component.
      *
      * @return \Samrap\Acf\Fluent\Builder

src/Fluent/Runner.php

@@ -25,6 +25,7 @@ class Runner
     protected $components = [
         'expect',
         'default',
+        'shortcodes',
         'escape',
     ];
 
@@ -48,6 +49,17 @@ public function getBehavior()
         return $this->behavior;
     }
 
+    /**
+     * Set the behavior.
+     *
+     * @param  \Samrap\Acf\Behaviors\BehaviorInterface  $behavior
+     * @return void
+     */
+    public function setBehavior(BehaviorInterface $behavior)
+    {
+        $this->behavior = $behavior;
+    }
+
     /**
      * Run the ACF 'get' behavior from the given builder.
      *
@@ -145,4 +157,22 @@ protected function runEscape($func, $value)
             ? call_user_func($func, $value)
             : $value;
     }
+
+    /**
+     * Do shortcodes on the given value.
+     *
+     * @param  bool  $_
+     * @param  mixed  $value
+     * @return mixed
+     */
+    protected function runShortcodes($_, $value)
+    {
+        if (! is_string($value)) {
+            throw new RunnerException(
+                'Cannot do shortcode on value of type '.gettype($value)
+            );
+        }
+
+        return do_shortcode($value);
+    }
 }

tests/Support/Mocks/functions.php

@@ -54,3 +54,8 @@ function esc_textarea($text)
 {
     return $text;
 }
+
+function do_shortcode($shortcode)
+{
+    return 'shortcode '.$shortcode;
+}

tests/Unit/AcfTest.php

@@ -44,7 +44,7 @@ public function subFieldBuilderUsesRunnerWithSubFieldBehavior()
     }
 
     /** @test */
-    public function optionBuilderUserRunnerWithFieldBehavior()
+    public function optionBuilderUsesRunnerWithFieldBehavior()
     {
         $this->assertInstanceOf(
             FieldBehavior::class,
@@ -58,6 +58,26 @@ public function optionBuilderUsesOptionPost()
         $this->assertEquals('option', Acf::option('foo')->id);
     }
 
+    /** @test */
+    public function sameBuilderInRunner()
+    {
+        $one = Acf::field('foo');
+        $two = Acf::field('bar');
+        $three = Acf::subField('baz');
+
+        // Make sure that both `field` queries use the same behavior instance...
+        $this->assertSame(
+            $one->getRunner()->getBehavior(),
+            $two->getRunner()->getBehavior()
+        );
+
+        // ...But the `subField` query should have its own behavior.
+        $this->assertNotSame(
+            $one->getRunner()->getBehavior(),
+            $three->getRunner()->getBehavior()
+        );
+    }
+
     /** @test */
     public function setIdOnFieldMethod()
     {

tests/Unit/Fluent/BuilderTest.php

@@ -6,92 +6,115 @@
 
 class BuilderTest extends TestCase
 {
-    /** @var \Samrap\Acf\Fluent\Builder */
-    protected $builder;
-
     public function setUp()
     {
         $this->setFields(['foo' => 'bar']);
-
-        $this->builder = new Builder(new RunnerMock);
     }
 
     /** @test */
     public function setField()
     {
-        $this->builder->field('foo');
+        $builder = new Builder(new RunnerMock);
+
+        $builder->field('foo');
 
-        $this->assertEquals('foo', $this->builder->field);
+        $this->assertEquals('foo', $builder->field);
     }
 
     /** @test */
     public function setExpect()
     {
-        $this->builder->expect('string');
+        $builder = new Builder(new RunnerMock);
 
-        $this->assertEquals('string', $this->builder->expect);
+        $builder->expect('string');
+
+        $this->assertEquals('string', $builder->expect);
     }
 
     /** @test */
     public function setDefault()
     {
-        $this->builder->default('bar');
+        $builder = new Builder(new RunnerMock);
+
+        $builder->default('bar');
 
-        $this->assertEquals('bar', $this->builder->default);
+        $this->assertEquals('bar', $builder->default);
     }
 
     /** @test */
     public function setEscape()
     {
-        $this->builder->escape();
+        $builder = new Builder(new RunnerMock);
 
-        $this->assertEquals('esc_html', $this->builder->escape);
+        $builder->escape();
+
+        $this->assertEquals('esc_html', $builder->escape);
     }
 
     /** @test */
     public function setEscapeAllowsCustomFunction()
     {
-        $this->builder->escape('htmlentities');
+        $builder = new Builder(new RunnerMock);
+
+        $builder->escape('htmlentities');
 
-        $this->assertEquals('htmlentities', $this->builder->escape);
+        $this->assertEquals('htmlentities', $builder->escape);
     }
 
     /** @test */
     public function setId()
     {
-        $this->builder->id(2);
+        $builder = new Builder(new RunnerMock);
+
+        $builder->id(2);
 
-        $this->assertEquals(2, $this->builder->id);
+        $this->assertEquals(2, $builder->id);
+    }
+
+    /** @test */
+    public function setShortcodes()
+    {
+        $builder = new Builder(new RunnerMock);
+
+        $builder->shortcodes();
+
+        $this->assertTrue($builder->shortcodes);
     }
 
     /** @test */
     public function setRaw()
     {
-        $this->builder->raw();
+        $builder = new Builder(new RunnerMock);
+
+        $builder->raw();
 
-        $this->assertTrue($this->builder->raw);
+        $this->assertTrue($builder->raw);
     }
 
     /** @test */
     public function fluentBuilder()
     {
-        $this->builder
+        $builder = new Builder(new RunnerMock);
+
+        $builder
             ->field('foo')
             ->id(2)
             ->expect('string')
             ->default('bar')
             ->escape();
 
-        $this->assertEquals('foo', $this->builder->field);
-        $this->assertEquals('string', $this->builder->expect);
-        $this->assertEquals('bar', $this->builder->default);
-        $this->assertEquals('esc_html', $this->builder->escape);
+        $this->assertEquals('foo', $builder->field);
+        $this->assertEquals('string', $builder->expect);
+        $this->assertEquals('bar', $builder->default);
+        $this->assertEquals('esc_html', $builder->escape);
     }
 
     /** @test */
     public function builderGet()
     {
-        $this->assertEquals('bar', $this->builder->field('foo')->get());
+        $builder = new Builder(new RunnerMock);
+
+        $this->assertEquals('bar', $builder->field('foo')->get());
     }
 
     /**
@@ -100,14 +123,18 @@ public function builderGet()
      */
     public function builderGetThrowsExceptionIfFieldNotSet()
     {
-        $this->builder->get();
+        $builder = new Builder(new RunnerMock);
+
+        $builder->get();
     }
 
     /** @test */
     public function builderUpdate()
     {
-        $this->builder->field('foo')->update('fiz');
+        $builder = new Builder(new RunnerMock);
+
+        $builder->field('foo')->update('fiz');
 
-        $this->assertEquals('fiz', $this->builder->field('foo')->get());
+        $this->assertEquals('fiz', $builder->field('foo')->get());
     }
 }