UPDATE move helper methods to invokable classes

Author: riccardodallavia

README.md

@@ -27,14 +27,26 @@ return [
 
     /*
     |--------------------------------------------------------------------------
-    | Helper class
+    | Helper macros
     |--------------------------------------------------------------------------
     |
-    | Here you may specify the fully qualified class name of the helper class.
+    | Here you may specify the full list of helper macros which will automatically
+    | be registered on boot.
+    | The key defines the method name, whereas the value should be the
+    | fully qualified name of the invokable class.
     |
     */
 
-   'helper' => Maize\Helpers\Helper::class,
+    'macros' => [
+        'anonymizeFilename' => \Maize\Helpers\Macros\AnonymizeFilename::class,
+        'classUsesTrait' => \Maize\Helpers\Macros\ClassUsesTrait::class,
+        'instanceofTypes' => \Maize\Helpers\Macros\InstanceofTypes::class,
+        'isUrl' => \Maize\Helpers\Macros\IsUrl::class,
+        'modelKeyName' => \Maize\Helpers\Macros\ModelKeyName::class,
+        'morphClassOf' => \Maize\Helpers\Macros\MorphClassOf::class,
+        'paginationLimit' => \Maize\Helpers\Macros\PaginationLimit::class,
+        'sanitizeUrl' => \Maize\Helpers\Macros\SanitizeUrl::class,
+    ],
 
 ];
 ```
@@ -53,55 +65,14 @@ hlp()->sanitizeUrl('mywebsite.com'); // using  the helper function
 
 ## Available methods
 
-- [`paginationLimit`](#paginationlimit)
 - [`anonymizeFilename`](#anonymizefilename)
-- [`sanitizeUrl`](#sanitizeurl)
-- [`instanceofTypes`](#instanceoftypes)
 - [`classUsesTrait`](#classusestrait)
-- [`morphClassOf`](#morphclassof)
+- [`instanceofTypes`](#instanceoftypes)
+- [`isUrl`](#isurl)
 - [`modelKeyName`](#modelkeyname)
-
-### `paginationLimit`
-
-The `paginationLimit` function returns the amount of items per page.
-
-It is useful when working with queries who need a pagination, and allows to define a default pagination limit and the max amount of items per page.
-
-It will also check whether the request's query string contains a `limit` parameter: if true, the given limit overrides the default limit.
-
-```php
-use App\Models\Article;
-
-// use the default pagination limit (16 items)
-// GET /api/articles
-Article::paginate(
-    hlp()->paginationLimit() // returns 16 items
-);
-
-// use the pagination limit given by the request query string
-// GET /api/articles?limit=20
-Article::paginate(
-    hlp()->paginationLimit() // returns 20 items
-);
-
-// provide a custom default pagination limit
-// GET /api/articles
-Article::paginate(
-    hlp()->paginationLimit(30) // returns 30 items
-);
-
-// when defined, the request query string limit overrides the default limit
-// GET /api/articles?limit=20
-Article::paginate(
-    hlp()->paginationLimit(30) // returns 20 items
-);
-
-// provide a max limit of items for each page
-// GET /api/articles?limit=200
-Article::paginate(
-    hlp()->paginationLimit(16, 50) // returns 50 items
-);
-```
+- [`morphClassOf`](#morphclassof)
+- [`paginationLimit`](#paginationlimit)
+- [`sanitizeUrl`](#sanitizeurl)
 
 ### `anonymizeFilename`
 
@@ -115,16 +86,24 @@ string $filename = 'my-custom-file.xml';
 hlp()->anonymizeFilename($filename);
 ```
 
-### `sanitizeUrl`
+### `classUsesTrait`
 
-The `sanitizeUrl` function prepends the specified url with the `https` protocol if none is set.
+The `classUsesTrait` function returns whether a class object or name uses the given trait or not.
 
 ```php
-hlp()->sanitizeUrl('http://innovation.h-farm.com'); // returns 'http://innovation.h-farm.com'
+use App\Models\User;
+use Exception;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
 
-hlp()->sanitizeUrl('innovation.h-farm.com'); // returns 'https://innovation.h-farm.com'
+$model = User::firstOrFail();
 
-hlp()->sanitizeUrl('') // returns an empty string
+hlp()->classUsesTrait(HasFactory::class, $model); // returns true
+
+hlp()->classUsesTrait(HasFactory::class, User::class); // returns true
+
+hlp()->classUsesTrait(Exception::class, $model); // returns false
+
+hlp()->classUsesTrait(Exception::class, User::class); // returns false
 ```
 
 ### `instanceofTypes`
@@ -148,24 +127,28 @@ hlp()->instanceofTypes($model, [
 ]); // returns true
 ```
 
-### `classUsesTrait`
+### `isUrl`
 
-The `classUsesTrait` function returns whether a class object or name uses the given trait or not.
+The `isUrl` function returns whether a string is a valid URL or not.
 
 ```php
-use App\Models\User;
-use Exception;
-use Illuminate\Database\Eloquent\Factories\HasFactory;
+hlp()->isUrl('https://my-application.test'); // returns true
 
-$model = User::firstOrFail();
+hlp()->isUrl('not-an-url'); // returns false
+```
 
-hlp()->classUsesTrait(HasFactory::class, $model); // returns true
+### `modelKeyName`
 
-hlp()->classUsesTrait(HasFactory::class, User::class); // returns true
+The `modelKeyName` function returns the key name of a given model object or class name.
 
-hlp()->classUsesTrait(Exception::class, $model); // returns false
+```php
+use App\Models\User;
 
-hlp()->classUsesTrait(Exception::class, User::class); // returns false
+$model = User::firstOrFail();
+
+hlp()->modelKeyName($model); // returns 'id'
+
+hlp()->modelKeyName(User::class); // returns 'id'
 ```
 
 ### `morphClassOf`
@@ -191,68 +174,126 @@ hlp()->morphClassOf($model); // returns 'user'
 hlp()->morphClassOf(User::class); // returns 'user'
 ```
 
-### `modelKeyName`
+### `paginationLimit`
 
-The `modelKeyName` function returns the key name of a given model object or class name.
+The `paginationLimit` function returns the amount of items per page.
+
+It is useful when working with queries who need a pagination, and allows to define a default pagination limit and the max amount of items per page.
+
+It will also check whether the request's query string contains a `limit` parameter: if true, the given limit overrides the default limit.
 
 ```php
-use App\Models\User;
+use App\Models\Article;
 
-$model = User::firstOrFail();
+// use the default pagination limit (16 items)
+// GET /api/articles
+Article::paginate(
+    hlp()->paginationLimit() // returns 16 items
+);
 
-hlp()->modelKeyName($model); // returns 'id'
+// use the pagination limit given by the request query string
+// GET /api/articles?limit=20
+Article::paginate(
+    hlp()->paginationLimit() // returns 20 items
+);
 
-hlp()->modelKeyName(User::class); // returns 'id'
+// provide a custom default pagination limit
+// GET /api/articles
+Article::paginate(
+    hlp()->paginationLimit(30) // returns 30 items
+);
+
+// when defined, the request query string limit overrides the default limit
+// GET /api/articles?limit=20
+Article::paginate(
+    hlp()->paginationLimit(30) // returns 20 items
+);
+
+// provide a max limit of items for each page
+// GET /api/articles?limit=200
+Article::paginate(
+    hlp()->paginationLimit(16, 50) // returns 50 items
+);
 ```
 
-## Extending the Helper class
+### `sanitizeUrl`
+
+The `sanitizeUrl` function prepends the specified url with the `https` protocol if none is set.
+
+```php
+hlp()->sanitizeUrl('http://innovation.h-farm.com'); // returns 'http://innovation.h-farm.com'
+
+hlp()->sanitizeUrl('innovation.h-farm.com'); // returns 'https://innovation.h-farm.com'
+
+hlp()->sanitizeUrl('') // returns an empty string
+```
 
-If needed, you can easily extend the `Helper` class to add your own methods.
+## Adding custom helper methods
 
-All you have to do is create a new class which overrides the `Helper` base class and adds all the methods you need.
-After that, you can override the `helper` attribute from `config/helpers.php` to match the newly created class.
+If needed, you can easily add your own helper methods.
 
-Here's an example of the output class:
+All you have to do is define your custom helper method using an invokable class:
 
 ```php
 <?php
 
-namespace Support\Helpers;
+namespace App\Helpers\Macros;
 
-use Maize\Helpers\Helper as BaseHelper;
-
-class Helper extends BaseHelper
+class Ping
 {
-    public static function awesomeHelper(): string
+    public function __invoke(): \Closure
     {
-        return "Just another awesome helper!";
+        return function (): string {
+            return 'pong';
+        };
     }
 }
 ```
 
-Whereas the `helpers.php` config file should look like this:
+After that, you can add your method to the `macros` attribute from `config/helpers.php`:
 
 ```php
 return [
 
     /*
     |--------------------------------------------------------------------------
-    | Helper class
+    | Helper macros
     |--------------------------------------------------------------------------
     |
-    | Here you may specify the fully qualified class name of the helper class.
+    | Here you may specify the full list of helper macros which will automatically
+    | be registered on boot.
+    | The key defines the method name, whereas the value should be the
+    | fully qualified name of the invokable class.
     |
     */
 
-   'helper' => Support\Helpers\Helper::class,
+    'macros' => [
+        'anonymizeFilename' => \Maize\Helpers\Macros\AnonymizeFilename::class,
+        'classUsesTrait' => \Maize\Helpers\Macros\ClassUsesTrait::class,
+        'instanceofTypes' => \Maize\Helpers\Macros\InstanceofTypes::class,
+        'isUrl' => \Maize\Helpers\Macros\IsUrl::class,
+        'modelKeyName' => \Maize\Helpers\Macros\ModelKeyName::class,
+        'morphClassOf' => \Maize\Helpers\Macros\MorphClassOf::class,
+        'paginationLimit' => \Maize\Helpers\Macros\PaginationLimit::class,
+        'sanitizeUrl' => \Maize\Helpers\Macros\SanitizeUrl::class,
+        'ping' => \App\Helpers\Macros\Ping::class,
+    ],
 
 ];
 ```
 
-You can then call all your custom-made helper methods using the `hlp()` function:
+Alternatively, if you need to define custom helpers at runtime, you can call the `macro` static method of the `Helper` class:
+
+```php
+use Maize\Helpers\Helper;
+
+Helper::macro('ping', fn (): string => 'pong');
+```
+
+You can now call your custom helper method with the `hlp()` helper method:
 
 ```php
-hlp()->awesomeHelper(); // returns "Just another awesome helper!";
+hlp()->ping(); // returns "pong";
 ```
 
 ## Testing

config/helpers.php

@@ -4,13 +4,25 @@
 
     /*
     |--------------------------------------------------------------------------
-    | Helper class
+    | Helper macros
     |--------------------------------------------------------------------------
     |
-    | Here you may specify the fully qualified class name of the helper class.
+    | Here you may specify the full list of helper macros which will automatically
+    | be registered on boot.
+    | The key defines the method name, whereas the value should be the
+    | fully qualified name of the invokable class.
     |
     */
 
-   'helper' => Maize\Helpers\Helper::class,
+    'macros' => [
+        'anonymizeFilename' => \Maize\Helpers\Macros\AnonymizeFilename::class,
+        'classUsesTrait' => \Maize\Helpers\Macros\ClassUsesTrait::class,
+        'instanceofTypes' => \Maize\Helpers\Macros\InstanceofTypes::class,
+        'isUrl' => \Maize\Helpers\Macros\IsUrl::class,
+        'modelKeyName' => \Maize\Helpers\Macros\ModelKeyName::class,
+        'morphClassOf' => \Maize\Helpers\Macros\MorphClassOf::class,
+        'paginationLimit' => \Maize\Helpers\Macros\PaginationLimit::class,
+        'sanitizeUrl' => \Maize\Helpers\Macros\SanitizeUrl::class,
+    ],
 
 ];