Squish (#16)

* Deprecate whitespace methods and trait in favor of `Str::squish()`.
* Improved PHPDoc types.
* Update version information.
* Link version shield to Packagist package page.
* Replace example with non-deprecated methods, move upgrade information down.

README.md

@@ -1,6 +1,6 @@
 # Text helpers
 
-![Packagist Version](https://img.shields.io/packagist/v/vendeka-nl/text)
+[![Packagist Version](https://img.shields.io/packagist/v/vendeka-nl/text)](https://packagist.org/packages/vendeka-nl/text)
 
 This package adds a handful of useful string helper methods to [`Illuminate\Support\Str`](https://laravel.com/docs/master/helpers#strings).
 
@@ -30,60 +30,28 @@ use Vendeka\Text\Text;
 Text::boot();
 ```
 
-## Upgrading
 
-### Upgrading from v1
-
-Version 2.0.x requires PHP 7.4 or higher. Version 3.0.x requires PHP 8.0 or higher.
-
-Next, update the package version of `vendeka-nl/text` to `"^3"` (or `"^2"` if you still are on PHP 7.4) in your composer.json and run `composer update vendeka-nl/text` to update the package.
-
-After updating the package, change your calls using the table below. 
-Replace all other references to `Vendeka\Text\Text` with `Illuminate\Support\Str`.
-
-| v1 | v2+ |
-|----|----|
-| `Vendeka\Text\Fluid` | `Illuminate\Support\Str::of()`
-| `Vendeka\Text\Text::changeCase()` | `Illuminate\Support\Str::lower()`<br>`Illuminate\Support\Str::upper()`<br>`Illuminate\Support\Str::ucfirst()` <br>`Illuminate\Support\Str::title()` |
-| `Vendeka\Text\Text::firstToUpperCase()` | `Illuminate\Support\Str::ucfirst()` |
-| `Vendeka\Text\Text::startsWith()` | `Illuminate\Support\Str::startsWith()` |
-| `Vendeka\Text\Text::toLowerCase()` | `Illuminate\Support\Str::lower()` |
-| `Vendeka\Text\Text::toTitleCase()` | `Illuminate\Support\Str::title()` |
-| `Vendeka\Text\Text::toUpperCase()` | `Illuminate\Support\Str::upper()` |
-
-### Upgrading from v3.0
-
-#### Deprecated `wrap` method
-
-Version 3.0.2 deprecated the `wrap` method because a method with the same name was added in `illuminate/support` v9.31 and overrides this packages' version.
-
-| v3.0 | v3.1+ |
-|----|----|
-|`Illuminate\Support\Str::wrap()`|`Illuminate\Support\Str::enclose()`|
-
-
-#### Deprecated `unwrap` method
-
-Version 3.1.1 deprecated the `unwrap` method because a method with the same name was added in `illuminate/support` v10.43 and overrides this packages' version.
-
-| v3.0 | v3.1.1+ |
-|----|----|
-|`Illuminate\Support\Str::unwrap()`|`Illuminate\Support\Str::unclose()`|
+# Usage
 
+This package adds a number of helpful methods to `Illuminate\Support\Str`. Check the [Laravel documentation](https://laravel.com/docs/11.x/helpers#strings-method-list) to see the available methods on `Illuminate\Support\Str`.
 
-# Usage
+```php
+use Illuminate\Support\Str;
 
-This package adds a number of helpfull methods to `Illuminate\Support\Str`. Check the [Laravel documentation](https://laravel.com/docs/9.x/helpers#strings-method-list) to see the available methods on `Illuminate\Support\Str`.
+Str::of('taco')->enclose('[', ']')->upper(); //=> '[TACO]'
+Str::unclose('/gift/', '/'); //=> 'gift'
+```
 
 
 ## Available methods
 
-Most methods are chainable using [`Illuminate\Support\Str::of()`](https://laravel.com/docs/9.x/helpers#fluent-strings) or Laravel 9's [`str()`](https://laravel.com/docs/9.x/helpers#method-str) helper function. Methods marked with an asterisk (*) are not chainable.
+Most methods are chainable using the `Illuminate\Support\Stringable` class, either by using [`Illuminate\Support\Str::of()`](https://laravel.com/docs/11.x/helpers#fluent-strings) or Laravel's [`str()`](https://laravel.com/docs/11.x/helpers#method-str) helper function. To convert to a string, either typecast to a `string` (`echo` will do this automatically) or call the `toString()` method. Methods marked with an asterisk (*) are not chainable
+
 - [`enclose`](#enclose)
 - [`exclamation`](#exclamation)
 - [`glue`](#glue)*
 - [`natural`](#natural)
-- [`normalizeWhitespace`](#normalizeWhitespace)
+- ~~[`normalizeWhitespace`](#normalizeWhitespace)~~
 - [`nullIfBlank`](#nullIfBlank)*
 - [`nullIfEmpty`](#nullIfEmpty)*
 - [`question`](#question)
@@ -97,19 +65,6 @@ Most methods are chainable using [`Illuminate\Support\Str::of()`](https://larave
 - ~~[`wrap`](#wrap)~~
 
 
-```php
-use Illuminate\Support\Str;
-
-Str::of('taco')->wrap('[', ']')->upper();   //=> '[TACO]'
-Str::unwrap('/gift/', '/');                 //=> 'gift'
-```
-
-Most methods return an instance of the class. To convert to a string, either typecast to a `string` (`echo` will do this automatically) or call the `toString()` method.
-
-
-## Available methods
-
-
 ### enclose
 
 *Since v3.0.2*
@@ -159,9 +114,11 @@ Str::natural('i_love_kebab'); // => 'I love kebab'
 ```
 
 
-### normalizeWhitespace
+### ~~normalizeWhitespace~~
 
 *Since v2.0.0*
+\
+**Deprecated since v3.3.1**:  No longer to be used in Laravel v10.42 or above, because `Illuminate\Support\Str::unwrap()` overrides this method. Use the `Str::squish()` method instead.
 
 Removes duplicate whitespace characters and trims.
 
@@ -359,6 +316,58 @@ Str::toWords('my-folder')->toString('/'); // => 'my/slug'
 ```
 
 
+# Upgrading
+
+## Upgrading from v1
+
+Version 2.0.x requires PHP 7.4 or higher. Version 3.0.x requires PHP 8.0 or higher. Version 3.3 requires PHP 8.2 or higher.
+
+Next, update the package version of `vendeka-nl/text` to `"^3"` in your composer.json and run `composer update vendeka-nl/text` to update the package.
+
+After updating the package, change your calls using the table below. 
+Replace all other references to `Vendeka\Text\Text` with `Illuminate\Support\Str`.
+
+| v1 | v2+ |
+|----|----|
+| `Vendeka\Text\Fluid` | `Illuminate\Support\Str::of()`
+| `Vendeka\Text\Text::changeCase()` | `Illuminate\Support\Str::lower()`<br>`Illuminate\Support\Str::upper()`<br>`Illuminate\Support\Str::ucfirst()` <br>`Illuminate\Support\Str::title()` |
+| `Vendeka\Text\Text::firstToUpperCase()` | `Illuminate\Support\Str::ucfirst()` |
+| `Vendeka\Text\Text::startsWith()` | `Illuminate\Support\Str::startsWith()` |
+| `Vendeka\Text\Text::toLowerCase()` | `Illuminate\Support\Str::lower()` |
+| `Vendeka\Text\Text::toTitleCase()` | `Illuminate\Support\Str::title()` |
+| `Vendeka\Text\Text::toUpperCase()` | `Illuminate\Support\Str::upper()` |
+
+## Upgrading from v3.0
+
+### Deprecated `wrap` method
+
+Version 3.0.2 deprecated the `wrap` method because a method with the same name was added in `illuminate/support` v9.31 and overrides this packages' version.
+
+| v3.0 | v3.1+ |
+|----|----|
+|`Illuminate\Support\Str::wrap()`|`Illuminate\Support\Str::enclose()`|
+
+
+### Deprecated `unwrap` method
+
+Version 3.1.1 deprecated the `unwrap` method because a method with the same name was added in `illuminate/support` v10.43 and overrides this packages' version.
+
+| v3.0 | v3.1.1+ |
+|----|----|
+|`Illuminate\Support\Str::unwrap()`|`Illuminate\Support\Str::unclose()`|
+
+
+## Upgrading from v3.2
+
+### Deprecated `normalizeWhitespace` method
+
+Version 3.1.1 deprecated the `normalizeWhitespace` method, in favor of `squish` method that comes with `illuminate/support`.
+
+| v3.2 | v3.3.1+ |
+|----|----|
+|`Illuminate\Support\Str::normalizeWhitespace()`|`Illuminate\Support\Str::squish()`|
+
+
 # Testing
 
 ```

src/Text.php

@@ -7,12 +7,9 @@
 use Vendeka\Text\Words;
 use Illuminate\Support\Str;
 use Illuminate\Support\Stringable;
-use Vendeka\Text\Traits\NormalizesWhitespace;
 
 class Text
 {
-    use NormalizesWhitespace;
-
     private static bool $isBooted = false;
 
     /**
@@ -79,7 +76,6 @@ public static function exclamation(string $text): string
      * 
      * @param string $glue
      * @param mixed $strings
-     * 
      * @return string
      */
     public static function glue(string $glue, ...$strings)
@@ -129,12 +125,13 @@ public static function natural(string $text): string
     /**
      * Removes duplicate whitespace characters and trim.
      * 
+     * @deprecated 3.3.1 Use `Str::squish()` method instead.
      * @param string $text 
      * @return string
      */
     public static function normalizeWhitespace(string $text): string
     {
-        return self::purgeWhitespace($text);
+        return Str::squish($text);
     }
 
     /**
@@ -238,7 +235,7 @@ public static function unclose(string $text, string|iterable $before, string|ite
      *
      * @param string $text
      * @param string|iterable $lead
-     * @return string|array
+     * @return string
      */
     public static function unprefix(string $text, string|iterable $lead): string
     {
@@ -258,7 +255,7 @@ public static function unprefix(string $text, string|iterable $lead): string
      *
      * @param string $text
      * @param string|iterable $cap
-     * @return string|array
+     * @return string
      */
     public static function unsuffix(string $text, string|iterable $cap): string
     {

src/Traits/IsStringable.php

@@ -5,6 +5,7 @@
 use Illuminate\Support\Stringable;
 
 /**
+ * @internal Provides method to convert to instance `Illuminate\Support\Stringable`.
  * @codeCoverageIgnore
  */
 trait IsStringable

src/Traits/NormalizesWhitespace.php

@@ -3,6 +3,8 @@
 namespace Vendeka\Text\Traits;
 
 /**
+ * @deprecated 3.3.1 This trait was only to be used internally and will be dropped in v4.
+ * @internal Used internally to trim and replace repeating whitespace characters with a single space.
  * @codeCoverageIgnore
  */
 trait NormalizesWhitespace

src/Words.php

@@ -3,14 +3,13 @@
 namespace Vendeka\Text;
 
 use Illuminate\Support\Collection;
+use Illuminate\Support\Str;
 use Stringable;
 use Vendeka\Text\Traits\IsStringable;
-use Vendeka\Text\Traits\NormalizesWhitespace;
 
 class Words extends Collection
 {
     use IsStringable;
-    use NormalizesWhitespace;
 
     /**
      * @param mixed $text 
@@ -21,7 +20,7 @@ public function __construct(mixed $text)
         {
             $text = preg_replace('/((?:[A-Z]\.?)+)/', ' $1', $text);
             $text = str_replace(['_', '-'], ' ', $text);
-            $text = self::purgeWhitespace($text);
+            $text = Str::squish($text);
             $text = explode(' ', $text);
         }