Add a wordWrap function

src/Utility/Text.php

@@ -312,6 +312,58 @@ class Text
     }
 
     /**
+     * Wraps a complete block of text to a specific width, can optionally wrap
+     * at word breaks.
+     *
+     * ### Options
+     *
+     * - `width` The width to wrap to. Defaults to 72.
+     * - `wordWrap` Only wrap on words breaks (spaces) Defaults to true.
+     * - `indent` String to indent with. Defaults to null.
+     * - `indentAt` 0 based index to start indenting at. Defaults to 0.
+     *
+     * @param string $text The text to format.
+     * @param array|int $options Array of options to use, or an integer to wrap the text to.
+     * @return string Formatted text.
+     */
+    public static function wrapBlock($text, $options = [])
+    {
+        if (is_numeric($options)) {
+            $options = ['width' => $options];
+        }
+        $options += ['width' => 72, 'wordWrap' => true, 'indent' => null, 'indentAt' => 0];
+
+        if (!empty($options['indentAt']) && $options['indentAt'] === 0) {
+            $indentLength = !empty($options['indent']) ? strlen($options['indent']) : 0;
+            $options['width'] = $options['width'] - $indentLength;
+            return self::wrap($text, $options);
+        }
+
+        $wrapped = self::wrap($text, $options);
+
+        if (!empty($options['indent'])) {
+            $indentationLength = !empty($options['indent']) ? strlen($options['indent']) : 0;
+            $chunks = explode("\n", $wrapped);
+            if (count($chunks) < 2) {
+                return $wrapped;
+            }
+            $toRewrap = '';
+            for ($i = $options['indentAt'], $len = count($chunks); $i < $len; $i++) {
+                $toRewrap .= substr($chunks[$i], $indentationLength) . ' ';
+                unset($chunks[$i]);
+            }
+            $options['width'] = $options['width'] - $indentationLength;
+            $options['indentAt'] = 0;
+            $rewrapped = self::wrap($toRewrap, $options);
+            $newChunks = explode("\n", $rewrapped);
+
+            $chunks = array_merge($chunks, $newChunks);
+            $wrapped =  implode("\n", $chunks);
+        }
+        return $wrapped;
+    }
+    
+    /**
      * Unicode and newline aware version of wordwrap.
      *
      * @param string $text The text to format.

tests/TestCase/Utility/TextTest.php

@@ -449,6 +449,56 @@ This is the song that never ends.
 TEXT;
         $this->assertTextEquals($expected, $result);
     }
+    /**
+     * test wrapBlock() indentical to wrap()
+     *
+     * @return void
+     */
+    public function testWrapBlockIndenticalToWrap()
+    {
+        $text = 'This is the song that never ends. This is the song that never ends. This is the song that never ends.';
+        $result = Text::wrapBlock($text, 33);
+        $expected = Text::wrap($text, 33);
+        $this->assertTextEquals($expected, $result);
+
+        $result = Text::wrapBlock($text, ['width' => 33, 'indentAt' => 0]);
+        $expected = Text::wrap($text, ['width' => 33, 'indentAt' => 0]);
+        $this->assertTextEquals($expected, $result);
+    }
+    /**
+     * test wrapBlock() indenting from first line
+     *
+     * @return void
+     */
+    public function testWrapBlockWithIndentAt0()
+    {
+        $text = 'This is the song that never ends. This is the song that never ends. This is the song that never ends.';
+        $result = Text::wrapBlock($text, ['width' => 33, 'indent' => "\t", 'indentAt' => 0]);
+        $expected = <<<TEXT
+	This is the song that never
+	ends. This is the song that
+	never ends. This is the song
+	that never ends.
+TEXT;
+        $this->assertTextEquals($expected, $result);
+    }
+    /**
+     * test wrapBlock() indenting from second line
+     *
+     * @return void
+     */
+    public function testWrapBlockWithIndentAt1()
+    {
+        $text = 'This is the song that never ends. This is the song that never ends. This is the song that never ends.';
+        $result = Text::wrapBlock($text, ['width' => 33, 'indent' => "\t", 'indentAt' => 1]);
+        $expected = <<<TEXT
+This is the song that never ends.
+	This is the song that never
+	ends. This is the song that
+	never ends.
+TEXT;
+        $this->assertTextEquals($expected, $result);
+    }
 
     /**
      * testTruncate method