imanghafoori/laravel-nullable

A package to help you write expressive defensive code in a functional manner

v1.2.9 2024-01-24 03:54 UTC

Requires

• php: ^7.1.3|7.2.*|7.3.*|7.4.*|8.0.*|8.1.*|8.2.*|8.3.*
• laravel/framework: ~5.1|6.*|7.*|8.*|9.*|10.*|11.*

Requires (Dev)

• mockery/mockery: ^1.0
• orchestra/testbench: ~4.0

Suggests

• imanghafoori/laravel-anypass: Allows you login with any password in local environment.
• imanghafoori/laravel-decorator: Allows you to easily apply the decorator pattern in a laravel app.
• imanghafoori/laravel-masterpass: You can easily set a master password without code change.
• imanghafoori/laravel-terminator: Gives you opportunity to refactor your controllers.
• imanghafoori/laravel-widgetize: Gives you a better structure and caching opportunity for your web pages.

MIT

• Iman Ghafoori

• php
• laravel
• laravel-package

README

Do not let "null" to impersonate your objects.

Functional programming paradigm in laravel

Built with ❤️ for every smart laravel developer

Null is usually used to represent a missing value (for ex when we can't find a row with a partcular Id we return null) And that is the BAD IDEA, we are going to kill off !!!

🔥 Installation:

composer require imanghafoori/laravel-nullable

This package exposes a nullable() global helper function with which you can wrap variables which sometimes are object and sometimes null.

Consider this:

$email = TwitterApi::find(1)->email;

Now this code is working fine But...

What if the user with ID of 1 gets deleted in future ?!

null->email and crap ! 😧

So if you forget to handle the null with an if statement, you will have errors.

You need something to FORCE you and the users of your class methods to handle the null cases.

To prevent such errors, you should code like this:

$user = $twitterApi->find($id);

if ($user === null) {
    return redirect()->route('page_not_found');
}

▶️ Nullables to rescue !!!

To refactor the code above, first

You have to change your repo class :

// the old way:

/**
* @return User|null            <---- consider here. We are returning two types !!!
*/
public function find ($id) {
     $user = TwitterApi::search($id);
     
     if (!$user) {
         return null;
     }
     return new User($user);   
}

The above code returns 2 types, and That is the source of confusion for method callers. They get ready for one type, and forget about the other.

Let's do a small change to it:

/**
 * @return Nullable        <---- we now have only one consistent type. Not two.
 */
public function find ($id) {
     $user = TwitterApi::search($id);
     
     if (!$user) {
         return new Nullable(null);   //  <----  instead of pure null;
     }
     $user = new User($user);   
     
     $message = 'Model Not Found with Id : '. $id;

     return new Nullable($user, [$message]);   //  <----  instead of User;
}

🔔 Now our method consistently returns Nullable objects, no matter what :)

After this change, no one can have access to the real meat of your repo (in this case User object) unless he/she gives a way to handle the null case. No if(is_null()) is required, No exception handling is required.

Remember PHP does not force us to write that if, and we as humen always tend to forget it.

And that makes a differnce ! Before it was easy to forget, but it is impossible to continue if you forget !!!

$userObj = $userRepo->find($id)->getOrSend(function ($message) {

  return redirect()->route('page_not_found')->with('error', $message);
});

// Call a static method.
$userObj = $twitterApi->find($id)->getOrSend([Response::class, 'pageNotFound']);

// or a get default value
$userObj = $twitterApi->find($id)->getOr(new User());

Now we are sure $user is not null and we can sleep better at night !

▶️ Testing:

An other advantage is that, if you use nullable and you forget to write a test that simulates the situations where null values are returned, phpunit code coverage highlights the closure you have passed to the ->getOrDo() (or similar methods) as none-covered, indicating that there is a missing test.

but if you return the object directly, you can get 100% code coverage without having a test covering nully situations, hence hidden errors may still lurk you at 100% coverage.

▶️ Q & A :

Why throwing exceptions is not always the best idea?!

When you throw an exception you should always ask your self. Is there any body out there to catch it ?? What if they forget to catch and handle the exception ?! It is the same issue as the null. It cases error.

The point is to give no way to continue, if they forget to handle the failures.

More from the author:

Laravel middlewarize (new*)

💎 You can put middleware on any method calls.

• https://github.com/imanghafoori1/laravel-middlewarize

Laravel Hey Man

💎 It allows to write expressive code to authorize, validate and authenticate.

• https://github.com/imanghafoori1/laravel-heyman

Laravel Terminator

💎 A minimal yet powerful package to give you opportunity to refactor your controllers.

• https://github.com/imanghafoori1/laravel-terminator

Laravel AnyPass

💎 It allows you login with any password in local environment only.

• https://github.com/imanghafoori1/laravel-anypass

Eloquent Relativity

💎 It allows you to decouple your eloquent models to reach a modular structure

• https://github.com/imanghafoori1/eloquent-relativity