Skip to content

Commit ec60ea3

Browse files
ultronoultrono
committed
Add read me, add instructions and sample to allow for IDE auto completion
1 parent 2628281 commit ec60ea3

File tree

2 files changed

+209
-2
lines changed

2 files changed

+209
-2
lines changed

‎README.md

Lines changed: 191 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[![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)
22
[![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)
33
[![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)
4-
![Travis (.org)](https://img.shields.io/travis/f9webltd/laravel-redirect-response-macros?style=flat-square)
4+
![Travis (.org)](https://travis-ci.com/f9webltd/laravel-redirect-response-macros.svg?branch=master&status=passed)
55
[![StyleCI Status](https://github.styleci.io/repos/278581318/shield)](https://github.styleci.io/repos/278581318)
66
[![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)
77

@@ -25,7 +25,195 @@ Optionally publish language files by running: `php artisan vendor:publish` and s
2525

2626
## Documentation
2727

28-
To follow ...
28+
This package allows for concise controller redirections by setting default flash data. It works as Laravels `RedirectResponse` class is "macroable".
29+
30+
For example the packages allows:
31+
32+
``` php
33+
public function store(FormRequest $request)
34+
{
35+
// create record ...
36+
return redirect()->route('posts.index')->created();
37+
}
38+
```
39+
40+
... instead of:
41+
42+
``` php
43+
public function store(FormRequest $request)
44+
{
45+
// create record ...
46+
return redirect()->route('posts.index')->with('success', 'The record was successfully created');
47+
}
48+
```
49+
50+
The former is of course much more concise and readable.
51+
52+
The package specifies several custom `RedirectResponse` macros that can be used on any of the native Laravel helpers that return the redirect response object.
53+
54+
The following methods are available.
55+
56+
#### `success()`
57+
58+
Flash message key: `success`
59+
Pass a message string to the macros.
60+
61+
``` php
62+
public function update(FormRequest $request, $id)
63+
{
64+
return back()->success('Everything is great!');
65+
}
66+
```
67+
68+
#### `info()`
69+
70+
Flash message key: `info`
71+
Pass a message string to the macros.
72+
73+
``` php
74+
public function update(FormRequest $request, $id)
75+
{
76+
return back()->info('Some information ...');
77+
}
78+
```
79+
80+
#### `danger()`
81+
82+
Flash message key: `danger`
83+
Pass a message string to the macros.
84+
85+
``` php
86+
public function update(FormRequest $request, $id)
87+
{
88+
return back()->danger('That action just is impossible!');
89+
}
90+
```
91+
92+
#### `warning()`
93+
94+
Flash message key: `warning`
95+
Pass a message string to the macros.
96+
97+
``` php
98+
public function update(FormRequest $request, $id)
99+
{
100+
return back()->warning('This could be risky ...');
101+
}
102+
```
103+
104+
There are further helper method available, that set the same type of flash data, but in a more readable manner:
105+
106+
#### `created()`
107+
108+
Flash message key: `success`
109+
Default message: `The record was successfully created`
110+
111+
``` php
112+
public function store(FormRequest $request)
113+
{
114+
// create record ...
115+
return redirect()->route('posts.index')->created();
116+
}
117+
```
118+
119+
Alternatively pass a url to display an message with a link to view the created record:
120+
121+
``` php
122+
public function store(FormRequest $request)
123+
{
124+
// create record ...
125+
return redirect()->route('posts.index')->created(
126+
route('posts.edit', $post)
127+
);
128+
}
129+
```
130+
131+
The flashed message will now be: `The record was successfully created. <a href="/posts/1/edit" class="alert-link">View inserted record</a>`.
132+
133+
#### `updated()`
134+
135+
Flash message key: `success`
136+
Default message: `The record was successfully updated`
137+
138+
``` php
139+
public function update(FormRequest $requestm int $id)
140+
{
141+
// update record ...
142+
return back()->updated();
143+
}
144+
```
145+
146+
To set a custom message, pass the desired text to the `updated()` function.
147+
148+
#### `deleted()`
149+
150+
Flash message key: `success`
151+
Default message: `The record was successfully deleted`
152+
153+
``` php
154+
public function update(Post $post)
155+
{
156+
$posts->delete();
157+
158+
return redirect()->route('posts.index')->deleted();
159+
}
160+
```
161+
162+
To set a custom message, pass the desired text to the `deleted()` function.
163+
164+
#### `error()`
165+
166+
Flash message key: `error`
167+
Specific message text should be passed.
168+
169+
``` php
170+
public function index()
171+
{
172+
// code ...
173+
return redirect()->route('dashboard')->error('You cannot do this thing!');
174+
}
175+
```
176+
177+
The function can detect the presence of exception object and call `getMessage()` as required:
178+
179+
``` php
180+
public function index()
181+
{
182+
try {
183+
$service->run();
184+
} catch (Exception $e) {
185+
return redirect()->route('dashboard')->error($e)
186+
}
187+
}
188+
```
189+
190+
#### `errorNotFound()`
191+
192+
Works in the same way as the `error()` macro and is intended to make controllers more concise.
193+
194+
The default message is `Sorry, the record could not be found.`.
195+
196+
#### `authorized()`
197+
198+
Flash message key: `success`
199+
Default message: `Welcome back, you have been securely logged in`
200+
201+
A custom message can optionally be provided.
202+
203+
#### `unAuthorized()`
204+
205+
Works in the same way as the `error()` macro and is intended to make controllers more concise.
206+
207+
The default message is `You do not have permission to perform that action`.
208+
209+
## IDE Autocompletion within PHPStorm
210+
211+
Autocompletion of "macroable" classes with PHPStorm currently difficult. As great as macros are, there is no solution to enable autocompletion.
212+
213+
At present, the following process will allow for autocompletion:
214+
215+
- Copy `resources/_ide_helper_macros.php` to a location within your project to allow PHP storm to index the additional class methods
216+
- Optionally add `_ide_helper_macros.php` to your `.gitignore` file
29217

30218
## Contribution
31219

@@ -48,3 +236,4 @@ If you discover any security related issues, please email rob@f9web.co.uk instea
48236
## License
49237

50238
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
239+

‎resources/_ide_helper_macros.php

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<?php
2+
3+
namespace Illuminate\Http;
4+
5+
/**
6+
* @method \Illuminate\Http\RedirectResponse success($message)
7+
* @method \Illuminate\Http\RedirectResponse info($message)
8+
* @method \Illuminate\Http\RedirectResponse danger($message)
9+
* @method \Illuminate\Http\RedirectResponse warning($message)
10+
* @method \Illuminate\Http\RedirectResponse created($route = null)
11+
* @method \Illuminate\Http\RedirectResponse updated($message = null)
12+
* @method \Illuminate\Http\RedirectResponse deleted($message = null)
13+
* @method \Illuminate\Http\RedirectResponse error($message = null)
14+
* @method \Illuminate\Http\RedirectResponse errorNotFound($message = null)
15+
* @method \Illuminate\Http\RedirectResponse authorized($message = null)
16+
* @method \Illuminate\Http\RedirectResponse unAuthorized($message = null)
17+
*/
18+
class RedirectResponse {}

0 commit comments

Comments
 (0)