Breaking change: Fix docs, force static methods to return strings

rather than Stringy instances

README.md

@@ -45,7 +45,7 @@ documentation.
     </tr>
     <tr>
         <td>[endsWith](#endswithstring-substring--boolean-casesensitive--true-)</td>
-        <td>[endsWithAny](#endsWithAnystring-substrings--boolean-casesensitive--true-)</td>
+        <td>[endsWithAny](#endswithanystring-substrings--boolean-casesensitive--true-)</td>
         <td>[ensureLeft](#ensureleftstring-substring)</td>
         <td>[ensureRight](#ensurerightstring-substring)</td>
     </tr>
@@ -77,7 +77,7 @@ documentation.
         <td>[isLowerCase](#islowercase)</td>
         <td>[isSerialized](#isserialized)</td>
         <td>[isUpperCase](#isuppercase)</td>
-        <td>[last](#last)</td>
+        <td>[last](#lastint-n)</td>
     </tr>
     <tr>
         <td>[length](#length)</td>
@@ -100,7 +100,7 @@ documentation.
     <tr>
         <td>[removeLeft](#removeleftstring-substring)</td>
         <td>[removeRight](#removerightstring-substring)</td>
-        <td>[repeat](#repeatmultiplier)</td>
+        <td>[repeat](#repeatint-multiplier)</td>
         <td>[replace](#replacestring-search-string-replacement)</td>
     </tr>
     <tr>
@@ -110,10 +110,10 @@ documentation.
         <td>[slugify](#slugify-string-replacement----)</td>
     </tr>
     <tr>
-        <td>[startsWith](#startswithstring-substring--boolean-casesensitive--true-)</td>
-        <td>[startsWithAny](#startswithanystring-substrings--boolean-casesensitive--true-)</td>
         <td>[slice](#sliceint-start--int-end-)</td>
         <td>[split](#splitstring-pattern--int-limit-)</td>
+        <td>[startsWith](#startswithstring-substring--boolean-casesensitive--true-)</td>
+        <td>[startsWithAny](#startswithanystring-substrings--boolean-casesensitive--true-)</td>
     </tr>
     <tr>
         <td>[stripWhitespace](#stripwhitespace)</td>
@@ -821,26 +821,6 @@ is also converted to lowercase.
 s('Using strings like fòô bàř')->slugify(); // 'using-strings-like-foo-bar'
 ```
 
-##### startsWith(string $substring [, boolean $caseSensitive = true ])
-
-Returns true if the string begins with $substring, false otherwise.
-By default, the comparison is case-sensitive, but can be made insensitive
-by setting $caseSensitive to false.
-
-```php
-s('FÒÔbàřbaz')->startsWith('fòôbàř', false); // true
-```
-
-##### startsWithAny(string[] $substrings [, boolean $caseSensitive = true ])
-
-Returns true if the string begins with any of $substrings, false
-otherwise. By default the comparison is case-sensitive, but can be made
-insensitive by setting $caseSensitive to false.
-
-```php
-s('FÒÔbàřbaz')->startsWith(['fòô', 'bàř'], false); // true
-```
-
 ##### slice(int $start [, int $end ])
 
 Returns the substring beginning at $start, and up to, but not including
@@ -862,6 +842,26 @@ results.
 s('foo,bar,baz')->split(',', 2); // ['foo', 'bar']
 ```
 
+##### startsWith(string $substring [, boolean $caseSensitive = true ])
+
+Returns true if the string begins with $substring, false otherwise.
+By default, the comparison is case-sensitive, but can be made insensitive
+by setting $caseSensitive to false.
+
+```php
+s('FÒÔbàřbaz')->startsWith('fòôbàř', false); // true
+```
+
+##### startsWithAny(string[] $substrings [, boolean $caseSensitive = true ])
+
+Returns true if the string begins with any of $substrings, false
+otherwise. By default the comparison is case-sensitive, but can be made
+insensitive by setting $caseSensitive to false.
+
+```php
+s('FÒÔbàřbaz')->startsWith(['fòô', 'bàř'], false); // true
+```
+
 ##### stripWhitespace()
 
 Strip all whitespace characters. This includes tabs and newline

src/StaticStringy.php

@@ -16,13 +16,14 @@ use ReflectionMethod;
  * @method static string chars(string $str, string $encoding = null)
  * @method static string collapseWhitespace(string $str, string $encoding = null)
  * @method static bool contains(string $str, string $needle, bool $caseSensitive = true, string $encoding = null)
- * @method static bool containsAll(string $str, string $needle, bool $caseSensitive = true, string $encoding = null)
+ * @method static bool containsAll(string $str, string[] $needle, bool $caseSensitive = true, string $encoding = null)
- * @method static bool containsAny(string $str, string $needle, bool $caseSensitive = true, string $encoding = null)
+ * @method static bool containsAny(string $str, string[] $needle, bool $caseSensitive = true, string $encoding = null)
  * @method static int count(string $str, string $encoding = null)
  * @method static int countSubstr(string $str, string $substring, bool $caseSensitive = true, string $encoding = null)
  * @method static string dasherize(string $str, string $encoding = null)
  * @method static string delimit(string $str, string $delimiter, string $encoding = null)
  * @method static bool endsWith(string $str, string $substring, bool $caseSensitive = true, string $encoding = null)
+ * @method static bool endsWithAny(string $str, string[] $substrings, bool $caseSensitive = true, string $encoding = null)
  * @method static string ensureLeft(string $str, string $substring, string $encoding = null)
  * @method static string ensureRight(string $str, string $substring, string $encoding = null)
  * @method static string first(string $str, int $n, string $encoding = null)
@@ -45,7 +46,7 @@ use ReflectionMethod;
  * @method static bool isUpperCase(string $str, string $encoding = null)
  * @method static string last(string $str, string $encoding = null)
  * @method static int length(string $str, string $encoding = null)
- * @method static Stringy[] lines(string $str, string $encoding = null)
+ * @method static string[] lines(string $str, string $encoding = null)
  * @method static string longestCommonPrefix(string $str, string $otherStr, string $encoding = null)
  * @method static string longestCommonSuffix(string $str, string $otherStr, string $encoding = null)
  * @method static string longestCommonSubstring(string $str, string $otherStr, string $encoding = null)
@@ -64,9 +65,11 @@ use ReflectionMethod;
  * @method static string safeTruncate(string $str, int $length, string $substring = '', string $encoding = null)
  * @method static string shuffle(string $str, string $encoding = null)
  * @method static string slugify(string $str, string $replacement = '-', string $encoding = null)
- * @method static bool startsWith(string $str, string $substring, bool $caseSensitive = true, string $encoding = null)
  * @method static string slice(string $str, int $start, int $end = null, string $encoding = null)
  * @method static string split(string $str, string $pattern, int $limit = null, string $encoding = null)
+ * @method static bool startsWith(string $str, string $substring, bool $caseSensitive = true, string $encoding = null)
+ * @method static bool startsWithAny(string $str, string[] $substrings, bool $caseSensitive = true, string $encoding = null)
+ * @method static string stripWhitespace(string $str, string $encoding = null)
  * @method static string substr(string $str, int $start, int $length = null, string $encoding = null)
  * @method static string surround(string $str, string $substring, string $encoding = null)
  * @method static string swapCase(string $str, string $encoding = null)
@@ -145,10 +148,14 @@ class StaticStringy
 
         $result = call_user_func_array([$stringy, $name], $args);
 
-        if (is_object($result) && $result instanceof Stringy) {
+        $cast = function($val) {
-            return (string) $result;
+            if (is_object($val) && $val instanceof Stringy) {
+                return (string) $val;
+            } else {
+                return $val;
             }
+        };
 
-        return $result;
+        return is_array($result) ? array_map($cast, $result) : $cast($result);
     }
 }

src/Stringy.php

@@ -219,7 +219,7 @@ class Stringy implements Countable, IteratorAggregate, ArrayAccess
      * default the comparison is case-sensitive, but can be made insensitive by
      * setting $caseSensitive to false.
      *
-     * @param  array  $needles       Substrings to look for
+     * @param  string[]  $needles       Substrings to look for
      * @param  bool      $caseSensitive Whether or not to enforce case-sensitivity
      * @return bool      Whether or not $str contains $needle
      */
@@ -243,7 +243,7 @@ class Stringy implements Countable, IteratorAggregate, ArrayAccess
      * default the comparison is case-sensitive, but can be made insensitive by
      * setting $caseSensitive to false.
      *
-     * @param  array  $needles       Substrings to look for
+     * @param  string[] $needles       Substrings to look for
      * @param  bool     $caseSensitive Whether or not to enforce case-sensitivity
      * @return bool     Whether or not $str contains $needle
      */
@@ -1180,7 +1180,8 @@ class Stringy implements Countable, IteratorAggregate, ArrayAccess
      * by setting $caseSensitive to false.
      *
      * @param  string $substring     The substring to look for
-     * @param  bool   $caseSensitive Whether or not to enforce case-sensitivity
+     * @param  bool   $caseSensitive Whether or not to enforce
+     *                               case-sensitivity
      * @return bool   Whether or not $str starts with $substring
      */
     public function startsWith($substring, $caseSensitive = true)

tests/StaticStringyTest.php

@@ -15,25 +15,38 @@ class StaticStringyTestCase extends PHPUnit_Framework_TestCase
     public function testEmptyArgsInvocation()
     {
         $result = S::toLowerCase();
-        $this->assertEquals('', (string) $result);
+        $this->assertEquals('', $result);
     }
 
     public function testInvocation()
     {
         $result = S::toLowerCase('FOOBAR');
-        $this->assertEquals('foobar', (string) $result);
+        $this->assertEquals('foobar', $result);
+        $this->assertInternalType('string', $result);
     }
 
     public function testPartialArgsInvocation()
     {
         $result = S::slice('foobar', 0, 3);
-        $this->assertEquals('foo', (string) $result);
+        $this->assertEquals('foo', $result);
+        $this->assertInternalType('string', $result);
     }
 
     public function testFullArgsInvocation()
     {
         $result = S::slice('fòôbàř', 0, 3, 'UTF-8');
-        $this->assertEquals('fòô', (string) $result);
+        $this->assertEquals('fòô', $result);
+        $this->assertInternalType('string', $result);
+    }
+
+    public function testArrayReturnValue()
+    {
+        $result = S::lines("a\nb");
+        $this->assertEquals(['a', 'b'], $result);
+        $this->assertInternalType('array', $result);
+        foreach ($result as $val) {
+            $this->assertInternalType('string', $val);
+        }
     }
 
     /**