From ec60ea3e735a5191f60ceabc7a60634594d98808 Mon Sep 17 00:00:00 2001 From: ultrono Date: Sat, 15 Aug 2020 16:58:25 +0100 Subject: [PATCH] Add read me, add instructions and sample to allow for IDE auto completion --- README.md | 193 ++++++++++++++++++++++++++++++- resources/_ide_helper_macros.php | 18 +++ 2 files changed, 209 insertions(+), 2 deletions(-) create mode 100644 resources/_ide_helper_macros.php diff --git a/README.md b/README.md index 43a174d..81ca06f 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [![Packagist Version](https://img.shields.io/packagist/v/f9webltd/laravel-redirect-response-macros?style=flat-square)](https://packagist.org/packages/f9webltd/laravel-redirect-response-macros) [![Scrutinizer coverage (GitHub/BitBucket)](https://img.shields.io/scrutinizer/coverage/g/f9webltd/laravel-redirect-response-macros/master?style=flat-square)](https://scrutinizer-ci.com/g/f9webltd/laravel-redirect-response-macros/?branch=master) [![Scrutinizer code quality (GitHub/Bitbucket)](https://img.shields.io/scrutinizer/quality/g/f9webltd/laravel-redirect-response-macros?style=flat-square)](https://scrutinizer-ci.com/g/f9webltd/laravel-redirect-response-macros/?branch=master) -![Travis (.org)](https://img.shields.io/travis/f9webltd/laravel-redirect-response-macros?style=flat-square) +![Travis (.org)](https://travis-ci.com/f9webltd/laravel-redirect-response-macros.svg?branch=master&status=passed) [![StyleCI Status](https://github.styleci.io/repos/278581318/shield)](https://github.styleci.io/repos/278581318) [![Packagist License](https://img.shields.io/packagist/l/f9webltd/laravel-redirect-response-macros?style=flat-square)](https://packagist.org/packages/f9webltd/laravel-redirect-response-macros) @@ -25,7 +25,195 @@ Optionally publish language files by running: `php artisan vendor:publish` and s ## Documentation -To follow ... +This package allows for concise controller redirections by setting default flash data. It works as Laravels `RedirectResponse` class is "macroable". + +For example the packages allows: + +``` php +public function store(FormRequest $request) +{ + // create record ... + return redirect()->route('posts.index')->created(); +} +``` + +... instead of: + +``` php +public function store(FormRequest $request) +{ + // create record ... + return redirect()->route('posts.index')->with('success', 'The record was successfully created'); +} +``` + +The former is of course much more concise and readable. + +The package specifies several custom `RedirectResponse` macros that can be used on any of the native Laravel helpers that return the redirect response object. + +The following methods are available. + +#### `success()` + +Flash message key: `success` +Pass a message string to the macros. + +``` php +public function update(FormRequest $request, $id) +{ + return back()->success('Everything is great!'); +} +``` + +#### `info()` + +Flash message key: `info` +Pass a message string to the macros. + +``` php +public function update(FormRequest $request, $id) +{ + return back()->info('Some information ...'); +} +``` + +#### `danger()` + +Flash message key: `danger` +Pass a message string to the macros. + +``` php +public function update(FormRequest $request, $id) +{ + return back()->danger('That action just is impossible!'); +} +``` + +#### `warning()` + +Flash message key: `warning` +Pass a message string to the macros. + +``` php +public function update(FormRequest $request, $id) +{ + return back()->warning('This could be risky ...'); +} +``` + +There are further helper method available, that set the same type of flash data, but in a more readable manner: + +#### `created()` + +Flash message key: `success` +Default message: `The record was successfully created` + +``` php +public function store(FormRequest $request) +{ + // create record ... + return redirect()->route('posts.index')->created(); +} +``` + +Alternatively pass a url to display an message with a link to view the created record: + +``` php +public function store(FormRequest $request) +{ + // create record ... + return redirect()->route('posts.index')->created( + route('posts.edit', $post) + ); +} +``` + +The flashed message will now be: `The record was successfully created. View inserted record`. + +#### `updated()` + +Flash message key: `success` +Default message: `The record was successfully updated` + +``` php +public function update(FormRequest $requestm int $id) +{ + // update record ... + return back()->updated(); +} +``` + +To set a custom message, pass the desired text to the `updated()` function. + +#### `deleted()` + +Flash message key: `success` +Default message: `The record was successfully deleted` + +``` php +public function update(Post $post) +{ + $posts->delete(); + + return redirect()->route('posts.index')->deleted(); +} +``` + +To set a custom message, pass the desired text to the `deleted()` function. + +#### `error()` + +Flash message key: `error` +Specific message text should be passed. + +``` php +public function index() +{ + // code ... + return redirect()->route('dashboard')->error('You cannot do this thing!'); +} +``` + +The function can detect the presence of exception object and call `getMessage()` as required: + +``` php +public function index() +{ + try { + $service->run(); + } catch (Exception $e) { + return redirect()->route('dashboard')->error($e) + } +} +``` + +#### `errorNotFound()` + +Works in the same way as the `error()` macro and is intended to make controllers more concise. + +The default message is `Sorry, the record could not be found.`. + +#### `authorized()` + +Flash message key: `success` +Default message: `Welcome back, you have been securely logged in` + +A custom message can optionally be provided. + +#### `unAuthorized()` + +Works in the same way as the `error()` macro and is intended to make controllers more concise. + +The default message is `You do not have permission to perform that action`. + +## IDE Autocompletion within PHPStorm + +Autocompletion of "macroable" classes with PHPStorm currently difficult. As great as macros are, there is no solution to enable autocompletion. + +At present, the following process will allow for autocompletion: + +- Copy `resources/_ide_helper_macros.php` to a location within your project to allow PHP storm to index the additional class methods +- Optionally add `_ide_helper_macros.php` to your `.gitignore` file ## Contribution @@ -48,3 +236,4 @@ If you discover any security related issues, please email rob@f9web.co.uk instea ## License The MIT License (MIT). Please see [License File](LICENSE.md) for more information. + diff --git a/resources/_ide_helper_macros.php b/resources/_ide_helper_macros.php new file mode 100644 index 0000000..a69182c --- /dev/null +++ b/resources/_ide_helper_macros.php @@ -0,0 +1,18 @@ +