Short answer : This package helps you clean up your controller code in a way that you have never seen before
composer require imanghafoori/laravel-terminator
No need to add any service providers.
- Laravel +5.1 and above
- Php 7.0 and above
- When you see that you have an endpoint from which you have to send back more than one type of response... Then this package is going to help you a lot.
Consider a typical login endpoint, It may return 5 type of responses in different cases:
- 1- User is already logged in, so redirect.
- 2- Successfull login
- 3- Invalid credentials error
- 4- Incorrect credentials error
- 5- Too many login attempts error
The fact that MVC frameworks force us to "return a response" from controllers prevents us from simplify controllers beyond a certain point. So we decide to break that jail and bring ourselves freedom.
The idea is : Any class in the application should be able to send back a response.
Controllers, "control" the execution flow of your code, and send commands to other objects, telling them what to do. Their responsibility is not returning a "response" back to the client and this is the philosophy of terminator package.
Consider the code below:
// BAD code : Too many conditions
// BAD code : In a single method
// BAD code : (@_@) (?_?)
// (It is not that bad, since it is a simplified example)
class AuthController {
public function login(Request $request)
{
$validator = Validator::make($request->all(), [
'email' => 'required|max:255||string',
'password' => 'required|confirmed||string',
]);
if ($validator->fails()) {
return redirect('/some-where')->withErrors($validator)->withInput(); // return response 1
}
// 2 - throttle Attempts
if ($this->hasTooManyLoginAttempts($request)) {
$this->fireLockoutEvent($request);
return $this->sendLockoutResponse($request); // return response 2
}
// 3 - handle valid Credentials
if ($this->attemptLogin($request)) {
return $this->sendLoginResponse($request); // return response 3
}
// 4 - handle invalid Credentials
$this->incrementLoginAttempts($request);
return $this->sendFailedLoginResponse($request); // return response 4
//These if blocks can not be extracted out. Can they ?
}
}With the current approach, this is as much as we can refactor at best. Why? because the controllers are asking for response, they are not telling what to do.
We do not want many if conditions all within a single method, it makes the method hard to understand and reason about.
// Good code
// Good code
// Good code
class LoginController
{
public function Login(Request $request)
{
// Here we are telling what to do (not asking them)
// No response, just commands, Nice ???
$this->validateRequest(); // 1
$this->throttleAttempts(); // 2
$this->handleValidCredentials(); // 3
$this->handleInvalidCredentials(); // 4
}
// private functions may sit here
...
}Using "respondWith()" does not prevent the normal execution flow of the framework to be interrupted. All the middlewares and other normal termination process of the laravel will happen as normal. So it is production ready! 🐬
1 - First, you should eliminate "return" statements in your controllers like this:
use \ImanGhafoori\Terminator\Facades\Responder;
class AuthController {
public function login(Request $request)
{
// 1 - Validate Request
$validator = Validator::make($request->all(), [
'email' => 'required|max:255||string',
'password' => 'required|confirmed||string',
]);
if ($validator->fails()) {
$response = redirect('/some-where')->withErrors($validator)->withInput();
respondWith($response); // <-- look here
}
// 2 - throttle Attempts
if ($this->hasTooManyLoginAttempts($request)) {
$this->fireLockoutEvent($request);
$response = $this->sendLockoutResponse($request);
respondWith($response); // <-- look here "no return!"
}
// 3 - handle valid Credentials
if ($this->attemptLogin($request)) {
$response = $this->sendLoginResponse($request);
respondWith($response); // <-- look here "no return!"
}
// 4 - handle invalid Credentials
$this->incrementLoginAttempts($request);
$response = $this->sendFailedLoginResponse($request)
respondWith($response); // <-- look here "no return!"
}
}Do you see how "return" keyword is now turned into regular function calls?!
2 - Now that we have got rid of return statements,then the rest is easy, It is now possible to extract each if block into a method like below:
class LoginController
{
public function Login(Request $request)
{
$this->validateRequest();
$this->throttleAttempts();
$this->handleValidCredentials();
$this->handleInvalidCredentials();
}
...
}All this package exposes for you is 2 global helper functions and 1 Facade:
- respondWith()
- sendAndTerminate()
- \ImanGhafoori\Terminator\TerminatorFacade::sendAndTerminate()
$response = response()->json($someData);
respondWith($response);
// or
respondWith()->json($someData);
// or an alias function for 'respondWith()' is 'sendAndTerminate':
sendAndTerminate($response);
// or use facade:
\ImanGhafoori\Terminator\TerminatorFacade::sendAndTerminate($response);In fact sendAndTerminate() ( or it's alias "respondWith" ) function can accept anything you normally return from a typical controller.
Let me mention that the "sendAndTerminate or respondWith" helper functions (like other laravel helper functions) can be easily mocked out and does not affect the testibility at all.
// Sample Mock
TerminatorFacade::shouldRecieve('sendAndTerminate')->once()->with($someResponse)->andReturn(true);In fact they make your application for testable, because your tests do not fail if you change the shape of your response.
You may wonder how this magic is working behind the scenes. In short it uses nothing more than a standard laravel "renderable exception".
We highly encourage you to take a look at the simple source code of the package to find out what's going on there. It is only a few lines of code.
💎 It allows to write expressive code to authorize, validate and authenticate.
💎 A minimal package that helps you login with any password on local environments.
💎 A minimal yet powerful package to give a better structure and caching opportunity for your laravel apps.
💎 A simple package that lets you easily impersonate your users.
As always if you found this package useful and you want to encourage us to maintain and work on it, Please press the star button to declare your willingness.
I believe in standardizing automobiles. I do not believe in standardizing human beings.
"Albert Einstein"