DEV Community: Gaurav Makhecha

Why don't you start writing tests?

Gaurav Makhecha — Mon, 08 Aug 2022 07:28:00 +0000

See how easy it is to get started with automated testing in Laravel

There are hundreds of articles on why you should write tests for your code. And I assume you have read them many times.

Many developers realize the importance of writing tests but just do not get started.

Why Not

Mainly because of some misunderstanding.

They face the fear of doing it wrong.
They think they're not good enough (yet) to write tests.
They are not sure which type of tests apply to their projects.

As someone who has been there, let me tell you these things are temporary. Once you start writing tests, all this will go away.

Why Not Today

If I were to tell you that it would take only 5-10 minutes of your time to get started with testing, would you mind starting now?

Let today be the start of something new.

William Shakespeare

Okay. So let's kick off our testing journey with a Laravel application. You may use an existing web application or create a new one.

In fact, you can follow this article even for any other programming language/framework as we are going to discuss the high-level stuff only.

Default tests with Laravel

Laravel comes with a couple of tests out of the box. Open your terminal and type:

php artisan test

And if you haven't messed anything up in your web app, you would be greeted with something like:

Great, we have a perfect starting point. Let's write our own tests now.

Some web app code

If you have a fresh new Laravel web application, please append the following code to the routes/web.php file before writing your first test.

use App\Models\User;
use Illuminate\Http\Request;

// existing code...

Route::post('/users', function (Request $request) {
    $validated = $request->validate([
        'name' => ['required', 'string', 'max:255'],
        'email' => ['required', 'email', 'max:255'],
        'password' => ['required', 'confirmed'],
    ]);

    User::create($validated);

    return back()->with('success', 'User created successfully.');
});

The following things are happening in this code:

We validate the form data.
We create the user in the database.
We redirect the user back with a success message.

And our tests should cover all these.

Create a new test file

We'll start by creating a new test file. Please execute the following command in your terminal:

php artisan make:test UserTest

A new test file should be created at tests/Feature/UserTest.php.

Heads up - Resetting the database

If your code and tests play with the database, you should reset your database after each of your tests to ensure that one test cannot affect the results of another one. Laravel makes it effortless by providing a trait that you can add to your test classes.

Please add the following trait in the UserTest.php file:

use Illuminate\Foundation\Testing\LazilyRefreshDatabase;

class UserTest extends TestCase
{
    use LazilyRefreshDatabase;

    // existing code...

With that done, let's bake tests.

Your first test - the Happy path

The default test file already covers a test for a GET request. Thus, we can directly write a test for a POST request.

When the user submits the form from the browser, a POST request is made with the inputs and values. We are going to simulate the same thing in our tests.

Please append the following code to the UserTest.php file:

    // existing code...

    public function test_new_user_can_be_added()
    {
        $response = $this->post('/users', [
            'name' => 'Gaurav',
            'email' => 'gauravmakhecha@gmail.com',
            'password' => '123456',
            'password_confirmation' => '123456',
        ]);

        $response->assertRedirect('/')
            ->assertSessionHas('success', 'User created successfully.');

        $this->assertDatabaseHas('users', [
            'name' => 'Gaurav',
            'email' => 'gauravmakhecha@gmail.com',
        ]);
    }

Laravel provides an easy way to make a POST request from your test files using the post() method. Using that, we make the request and verify that user details are added to the database and the response is a redirect with the proper message in the session.

Wasn't this straightforward? Let's try one more.

Test for the validation

How about adding a test to make sure that our validation works as expected? Please append the following code to the UserTest.php file:

    // existing code...

    public function test_new_user_data_is_validated()
    {
        $response = $this->post('/users', [
            'name' => '',
            'email' => 'not_email_format',
            'password' => '123456',
            'password_confirmation' => '456789',
        ]);

        $response->assertStatus(302)
            ->assertSessionHasErrors(['name', 'email', 'password']);
    }

Here, we pass invalid data for the form inputs and confirm (assert) that there is a redirect response (HTTP status code 302) and that there are validation errors in the session.

Test for the unique email address

The business requirement is that the email address of each user has to be unique so let us add a test for the same. Append this test to the UserTest.php file:

    // existing code...

    public function test_new_user_with_same_email_cannot_be_added()
    {
        User::factory()->create([
            'email' => 'gauravmakhecha@gmail.com',
        ]);

        $response = $this->post('/users', [
            'name' => 'Gaurav',
            'email' => 'gauravmakhecha@gmail.com',
            'password' => '123456',
            'password_confirmation' => '123456',
        ]);

        $response->assertStatus(302)
            ->assertSessionDoesntHaveErrors(['name', 'password'])
            ->assertSessionHasErrors(['email']);
    }

This test uses Laravel Factory to add a user to the database and then tries to make a POST request with the same email address. Let us run tests and see the results.

Oops, it failed. And the reason? We missed adding the unique validation in our code.

The Fix

Now your test is guiding you with the development. (Yes TDD!)

Please make the following update in the routes/web.php file:

-        'email' => ['required', 'email', 'max:255'],
+        'email' => ['required', 'email', 'max:255', 'unique:users'],

Once updated, give yourself a pat on the back and run the tests again (php artisan test)

What more?

Did you realize you are now officially a developer who writes automated tests? Congrats!

Need more examples? Check this directory from the official Laravel repository for tests related to various modules.

The goal of this article is just to get you started with writing tests. Not to cover different use cases or scenarios. Hence, I limit the practical coding here and would like to share a few other things to help you progress with it.

Patterns that can help you

Many developers aren't sure for which parts of their code should they write tests. The simplest answer is: Try to write automated tests for all the functionality that you check while manually testing your web app.

In this example, we would have checked the DB entry, the validation messages, and the redirect while manually testing the web app. And that is what our automated tests covered.

Here are a couple of patterns to help you plan your tests:

1. Given-When-Then

2. Arrange-Act-Assert

Both are similar so you can use any of them. The idea is:

First, you set the scene (Add existing DB records, log in a user, etc.)
Then you take an action (Visit a URL, submit a form, etc.)
Finally, you verify the results/effects (A DB entry, a session call, response status code, etc.)

This way can generally help you in writing most of the test cases.

Moreover, we have a dedicated article about writing tests only for your code to guide you around the test boundaries.

(Not so) Complex Stuff

What we covered in this article are Feature tests. There are many other types of tests (Unit tests, Feature tests, Integration tests, Acceptance tests, etc.).

Do not hurry to learn/use all of them, you don't have to. You will feel the need yourself if/when the time arrives.

Topics like mocking and stubbing fall in the same category. Believe me, it is not compulsory to use them. But keep in mind they are quite handy for medium to big-size projects. We use them in our projects and can't live without them.

A Note on PEST

We use PEST for writing tests but I decided not to include that in this article to keep things simple. I wish (and am sure) it would come out of the box with Laravel.

To The Moon

I hope this article gets you started with writing tests and you never stop in the future. Feel free to comment below in case of any questions. May those tools give you more testing features 😉

And if any of your friends are also giving excuses to start writing tests, how about sharing this article with them for the push?

Cheers and regards.

An easier way to manage HTML DOM using Javascript

Gaurav Makhecha — Fri, 15 Apr 2022 14:37:08 +0000

Why you should use HTML Code generation methods as a last resort

Training

We hire freshers and train them in-house here at Freshbits. A lot of our own learning happens when we teach basic stuff to them.

Out of that, one of the random basic stuff that I would like to share today is about HTML code generation using Javascript.

Examples

We get the beginners to add some interactivity to the HTML pages that they have built using Javascript. It could be:

Add to cart functionality on the e-commerce page
Delete item functionality on the products listing page
Add address functionality on the checkout page, etc.

Javascript frameworks like React, Vue, or Angular are not in their syllabus yet. They use jQuery or vanilla JS for these kinds of developments.

With the fresh opportunity on hand and limited working experience, they are generally excited to go for it and come up with something like the following.

The go-to old way 💩

I will take the code done by our newest team member, Utsav, as an example. He was given the task of coding the add to cart functionality. As we expected, he coded the functionality this way:

function displayCart() {
    // Abbreviating other stuff to focus on the core topic...

    for (let i = 0; i < cart.length; i++) {
        var imageTag = document.createElement('img');
        imageTag.src = cart[i].img;
        imageTag.setAttribute('class', 'w-10 h-10 object-cover rounded-md');
        document.getElementById('cart-item-' + i).appendChild(imageTag);

        var nameTag = document.createElement('span');
        nameTag.setAttribute('class', 'ml-4 font-semibold text-sm');
        nameTag.innerHTML = cart[i].name;
        document.getElementById('cart-item-' + id).appendChild(nameTag);

        var priceTag = document.createElement('div');
        priceTag.innerHTML = cart[i].price;
        document.getElementById('cart-item-' + id).appendChild(priceTag);

        var deleteTag = document.createElement('button');
        deleteTag.setAttribute('class', 'px-3 py-1 rounded-md bg-red-300 text-white');
        deleteTag.setAttribute('onclick', 'removeFromCart(' + cart[i].id + ')');
        deleteTag.innerHTML = "x";
        document.getElementById('cart-item-' + id).appendChild(deleteTag);

        // ...
    }
}

There is nothing wrong with this approach. It is just less readable and maintainable. What if we want to add more elements to this cart? What if we wish to change styles?

Some might argue jQuery can make it better. While those long lines of code would be shorter, the main issue still stays there: managing changes in the final HTML output

Reading and modifying the HTML directly is easier. Let's see how.

Another way 🙅

We can rewrite the same example as the following:

function displayCart() {
    // Abbreviating other stuff to focus on the core topic...

    for (let i = 0; i < cart.length; i++) {
        var cartItemHtml = [
            '<div id="cart-item-' + i + '">',
                '<img class="w-10 h-10 object-cover rounded-md" src="' + cart[i].img + '" />',
                '<span class="ml-4 font-semibold text-sm">' + cart[i].name + '</span>',
                '<div>' + cart[i].price + '</div>',
                '<button class="px-3 py-1 rounded-md bg-red-300 text-white" onclick="removeFromCart(' + cart[i].id + ')">x</button>',
            '</div>'
        ].join("\n");

        // ...
    }
}

There is much better readability now. We can see what the final HTML is gonna look like. But, the HTML code is merged into Javascript so we have to play with those quotes a lot. One step further is to make the HTML code independent.

Even better way 🤗

There is a template HTML tag that is not shown on the page by default. We can use it to host our HTML code like:

<template id="cart-item">
    <div>
        <img class="w-10 h-10 object-cover rounded-md cart-item-image" />
        <span class="ml-4 font-semibold text-sm cart-item-name"></span>
        <div class="cart-item-price"></div>
        <button class="px-3 py-1 rounded-md bg-red-300 text-white cart-item-delete">x</button>
    </div>
</template>

Looks like the code we can easily maintain, right? Now how do we use it in the Javascript you asked?

function displayCart() {
    // Abbreviating other stuff to focus on the core topic...

    var template = document.getElementById('cart-item');

    for (let i = 0; i < cart.length; i++) {
        var cartItemTag = template.content.cloneNode(true);

        cartItemTag.querySelector("img.cart-item-image").src = cart[i].img; 
        cartItemTag.querySelector("span.cart-item-name").innerHTML = cart[i].name;
        cartItemTag.querySelector("div.cart-item-price").innerHTML = cart[i].price;
        cartItemTag.querySelector("button.cart-item-delete").onclick = function() { removeFromCart(cart[i].id) };
    }
}

This way, our Javascript can directly target each element inside the template and set the attributes and content respectively.

Is there any way to take this one step further? If you have any ideas, please do share.

Wind up

This learning is mainly for beginners when they are getting started with HTML and Javascript. As they progress, there are more options like using templating engines or going with full-fledged JS frameworks where you manage the data and the framework takes care of the DOM updates via reactivity.

That's it. If you have some JS code generating HTML, try the template tag today and let us know how it goes. See you on the flip side.

Credits: Cover Photo by Hal Gatewood on Unsplash

Write tests only for your own code

Gaurav Makhecha — Sat, 09 Apr 2022 14:51:58 +0000

Real-life example to answer 'what should I test?'

The developers who are just getting started with writing tests often get confused about what to test and how to test it 'properly'. Terms like Feature tests, Unit tests, Integration tests, and Acceptance tests are overwhelming.

But It's easier than most people think. You just need to write the test code that confirms whether your web app code does what it is supposed to do. Nothing more, nothing less.

Example

Let's take an example to make it clear. We have an open-source package called Laravel Log Enhancer that adds contextual data to the Laravel log entries.

The default Laravel log entry looks something like this:

And the package improves it to:

This package has been downloaded 222k+ times but let me tell you a secret 🤫. It is just connecting the dots and has a tiny codebase.

Laravel uses the Monolog library to manage the logging module. And Monolog offers something called processors to add extra data for all the log entries.

Okay, with the introduction out of our way, we can take a look at some code:

foreach ($logger->getHandlers() as $handler) {
    if (config('laravel_log_enhancer.log_request_details')) {
        $handler->pushProcessor(new WebProcessor);
    }

    if (config('laravel_log_enhancer.log_memory_usage')) {
        $handler->pushProcessor(new MemoryUsageProcessor);
    }

    $handler->pushProcessor(new RequestDataProcessor);
}

This piece of code is the heart of the package. Based on the configuration, it is just pushing the processor(s) to the Monolog handlers. The rest of the work is done by the Monolog library.

Tests for our example

Theoretically, our log enhancer package is supposed to add extra data to the log entries. Hence we should write automated tests that verify that behavior. Right?

Should it be something like:

/** @test */
public function it_adds_extra_data_to_the_log_entries()
{
    // Given
    config(['laravel_log_enhancer.log_memory_usage' => true]);
    config(['laravel_log_enhancer.log_request_details' => true]);

    // When
    // Run the code that logs something

    // Then
    // Fetch the log entry and check whether extra details are present in it
}

No!!

The package is only pushing some processors to the handlers. It shouldn't worry about what happens to the final log entry. It is the responsibility of the Monolog tests to verify that part. Makes sense? Good.

With that understanding, let's take a look at the actual test code from the package:

/** @test */
public function it_adds_respective_processors_to_the_log_handler()
{
    config(['laravel_log_enhancer.log_memory_usage' => true]);
    config(['laravel_log_enhancer.log_request_details' => true]);
    $logger = $this->app[Logger::class];

    $handlers = $logger->getHandlers();
    foreach ($handlers as $handler) {
        $this->assertInstanceOf(RequestDataProcessor::class, $handler->popProcessor());
        $this->assertInstanceOf(MemoryUsageProcessor::class, $handler->popProcessor());
        $this->assertInstanceOf(WebProcessor::class, $handler->popProcessor());
    }
}

This test is confirming exactly what our package is doing: adding processors to the handlers. Nothing more, nothing less.

Rest

I hope this example helps you decide the boundaries of your tests and increase your confidence in writing them.

Do you have any other examples in mind that explain what to test? Feel free to comment and share. See you!

Credits - Cover Photo by Paul Skorupskas on Unsplash

Custom authentication guard in Laravel Sanctum

Gaurav Makhecha — Tue, 29 Mar 2022 14:47:17 +0000

How to specify auth guard when using multiple guards with Sanctum

Preamble

Laravel Sanctum is the go-to solution for token-based API authentication and SPA (Single page application) authentication. It uses an authentication guard when performing the SPA authentication.

By default, the web guard is used as per the configuration file. The same guard is used in the default Laravel request authentication as well.

If your web app has multiple panels (say, admin, manager, customer, etc.), you'd be using multiple authentication guards. And there is a way to specify a guard to the auth middleware like:

Route::get('/setup', function () {
    // Only the users authenticated via the admin guard can visit this page.
})->middleware('auth:admin');

But in the case of Sanctum, there is no way to specify the guard. The word sanctum itself is used in the place of the guard name:

Route::get('/setup', function () {
    // The default `web` guard is used. There is no option to specify any other guard name here.
})->middleware('auth:sanctum');

How do we use the non-default guard then? Many developers have faced this issue. Let's solve it.

Solution

Step 1: Create a middleware

We will create a new middleware that will set the authentication guard for us based on the URL. Let us call it SetSanctumGuard:

<?php

declare(strict_types=1);

namespace App\Http\Middleware;

use Closure;
use Illuminate\Support\Str;

class SetSanctumGuard
{
    public function handle($request, Closure $next)
    {
        if (Str::startsWith($request->getRequestUri(), '/api/admin/')) {
            config(['sanctum.guard' => 'admin']);
        } elseif (Str::startsWith($request->getRequestUri(), '/api/manager/')) {
            config(['sanctum.guard' => 'manager']);
        } elseif (Str::startsWith($request->getRequestUri(), '/api/customer/')) {
            config(['sanctum.guard' => 'customer']);
        }

        return $next($request);
    }
}

Assuming that our web app follows this pattern in the API endpoints, we can decide the auth guard dynamically inside the middleware. Or you can try any other way as per your web app scenario to decide the guard.

Step 2: Enable the middleware

There are multiple ways to specify a middleware. In this case, we can simply add it to the api array inside the app/Http/Kernel.php file.

protected $middlewareGroups = [
    'web' => [
        // ...
    ],

    'api' => [
        \App\Http\Middleware\SetSanctumGuard::class,
        // ...
    ],
];

Step 3: Add a note in the config file (Optional)

To assure that none of the team members (or even yourself) get surprises in the future, it is a good idea to note this in the config/sanctum.php file. I do it like:

return [
    'guard' => '', // This is set by the `SetSanctumGuard` middleware

    //...
];

And with this, your web app should be using the respective auth guard to protect the routes as per the user type.

Cheers

I hope Sanctum allows this customization in the near future. And we will not need to create a custom middleware for this use case.

Until then, enjoy this quick hack and build powerful Laravel web apps. Have fun!

Credits - Cover Photo by Glenn Carstens-Peters on Unsplash

PHP Namespaces are not the same as the Directory Structure

Gaurav Makhecha — Wed, 16 Mar 2022 14:46:03 +0000

Let's start with a question: We have a PHP class SalesController.php with the namespace App/Http/Controllers and it is located at app/Http/Controllers/SalesController.php

Where do you think the class Sale.php with the namespace App/Domain/Sales would be located?

Did you say app/Domain/Sales/Sale.php? Are you sure?

...

Well, it is located at src/Domain/Sales/Sale.php and it works.

Why so

Thanks to the PSR-4 autoloading, we can define the namespaces prefix and their corresponding base directories.

Following is the composer configuration to clear the doubt:

{
    "autoload": {
        "psr-4": {
            "App\\Http\\": "app/Http",
            "App\\Domain\\": "src/Domain"
        }
    }
}

Reasoning

First of all, namespacing allows you to divide your code files into multiple groups. That allows you to set the same name for two different classes as far as they belong to different namespaces.

This flexibility allows developers to follow their own conventions over the framework conventions keeping all the parties happy.

One additional benefit when using namespaces in the code is easier directory renames. No need to do 'find & replace' in all the files that require your classes. Changing the base directory of the namespace does the job.

Fun Fact

You can set multiple base directories for a single namespace prefix. Example:

{
    "autoload": {
        "psr-4": { "Domain\\": ["src/", "lib/"] }
    }
}

Not sure why one would go for this as it is a bit confusing. But it's possible, however.

Story ends

In case you cannot find a class or directory by following the namespace words, do check the autoload config once. You may get the answer. Sayonara!

Credits - Cover Photo by Randy Fath on Unsplash

The correct way to pass Methods as Event Handlers in Javascript

Gaurav Makhecha — Thu, 10 Mar 2022 13:35:15 +0000

Those parentheses make a BIG difference and change the result

One of my colleagues wasn't receiving the expected parameters in a JS method the other day. He was trying to make a third-party Vue.js plugin work in a project (as we all do with fluctuating confidence).

Let's go through a simple example with vanilla Javascript but the rule applies everywhere (including your favorite JS framework).

document.getElementById("just-do-it").addEventListener("click", spreadHappiness());

function spreadHappiness() {
    console.log('You are awesome');
}

What do you think will happen when a user clicks on that button?

Guessed it?

Nothing!

The method gets called upon page load and nothing happens when the button is clicked. Hmm...

Did you notice that we have put the parentheses () after method name spreadHappiness() in the first line?

It is that classic call-by-reference vs call-by-value thing.

That line should have been written like this (with parentheses removed):

document.getElementById("just-do-it").addEventListener("click", spreadHappiness);

And with that, clicking on that button would log the statement in the browser console as expected.

Now, did you know that the event handler receives an object based on the Event interface as a parameter? This means you can use the Event metadata in your method. Like so:

function spreadHappiness(event) {
    console.log(event.type); // click
}

So, you should skip those parentheses when passing a method name as an event handler in most cases. When one needs to get the event handler dynamically, calling another method and returning it makes sense.

Closing

In short, putting those parentheses after the method name while specifying the event handler is not an optional thing. It changes the result.

method(): Executed instantly and the return value used as the event handler.

method: Used as the event handler and it receives the parameters when called.

Again, Doing a method call and passing the method reference are two different things and developers, especially beginners, should be aware of this difference.

Do any of your friends need to know this? Share this article with them to make their debugging life easier.

Calling Alpine.js methods from third-party scripts

Gaurav Makhecha — Tue, 08 Mar 2022 04:57:03 +0000

How we made Alpine-powered page understand Google Map events

Recently, we faced a small challenge when implementing Google Map on an Alpine.js powered page. Key points:

Map markers data is loaded in the Alpine.js store
The Google Map is outside the Alpine.js scope so cannot call Alpine method directly after its loaded

There was no way we could show those map markers on the Google Map.

After some surfing, this thread gave a hint. Let us go through the actual code to set up the base.

Google Maps related code

<div class="container">
    <div id="google-map" style="height: 600px;"></div>
</div>

...

<script async src="https://maps.googleapis.com/maps/api/js?key=APIKEY&callback=renderMap"></script>

<script>
    var googleMapObject;

    function renderMap() {
        googleMapObject = new google.maps.Map(document.getElementById("google-map"), {
            // Map config
        });
    }
</script>

And here's the Alpine.js setup code

<script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>

<script>
    document.addEventListener('alpine:init', () => {
        Alpine.store('app', {
            mapMarkers: [
                // Pre-loaded markers data
            ]
        });
    });
</script>

Solution

Events to the rescue. You can just fire a custom Javascript window event from the Google Maps object and make Alpine listen to it. Let's see the code:

<script>
    function renderMap() {
        // initialize map code

        var mapLoadedEvent = new Event('map-loaded');
        window.dispatchEvent(mapLoadedEvent);
    }
</script>

First, we are firing the custom JS event called map-loaded once the Google Map is loaded.

<div class="container" x-data @map-loaded.window="$store.app.addAllMarkers()">
    <div id="google-map" style="height: 600px;"></div>
</div>

This HTML code listens to that event and calls the addAllMarkers Alpine method. With that, our Google Map can call the Alpine.js method to show the map markers.

Lastly, our Alpine method can do the rest.

<script>
    var googleMapObject;

    document.addEventListener('alpine:init', () => {
        Alpine.store('app', {
            mapMarkers: [
                // Pre-loaded markers data
            ],

            addAllMarkers() {
                this.mapMarkers.forEach(function (mapMarker) {
                    new google.maps.Marker({
                        // Map marker config
                    });
                });
            },
        });
    });
</script>

We did this for Google Maps but you can do the same with any other third-party JS library using the custom Javascript window event.

Important to Note that a CustomEvent is different from a regular JS Event. Check this Stackoverflow answer for details.

Cheers!

What, why and how of PHP Composer

Gaurav Makhecha — Thu, 14 Jun 2018 14:18:30 +0000

Let's demystify the package manager Laravel and other frameworks use

Since developers have realized the power and benefits of the DRY approach, lots of frameworks and libraries have been crafted privately and open-source.

If you're someone like me (myself 2 years ago to be precise), you might say - "Why all these new frameworks are not allowing a direct .zip download? Why do I have to install (and learn) this new Composer thing just to download a framework?"

Back in the days when I was using Codeigniter and CakePHP 2, I would just download .zip file, extract it in my project directory and start developing. So neat, right? Read on.

Then, I witnessed new version CakePHP 3 in 2015 (so unlucky I didn't try Laravel that time). It was forcing me to use composer to download the framework and I was very new to it. I was complaining, like others, until I realised how much time and headaches it is going to save for me.

What it Composer?

Composer is a dependency manager and autoloading expert for PHP.

Have you heard about or used npm? (or yarn) Or if you're a Rubyist, Bundler must not be new to you. Composer provides similar functionality for the PHP world. It used to be PEAR (PHP Extension and Application Repository) in early days.

One important thing to note here is that the open-source packages generally recide on Packagist and composer downloads the dependencies from there, unless you specify other location. Packagist, in turn, keep and updates the code from Git/Svn repositories. And you can also use private repository with composer by using Private packagist or hosting them yourself.

I hate theory. Let's have some practical talk.

Pains that Composer fixes

Following are some of pains that Composer has relieved:

Dependency Management

When you are working on a new project using a framework, you depend on it's updates. As they release new versions with bug fixes and new features, you should keep the framework updated for security, performance, and other reasons.

But, it's a pain to manually download it everytime, replace the existing files and test things again. It takes time. And that is why there are so many old codebases relying on the versions of frameworks that are no longer supported. Working on legacy projects is something that all of us try to avoid, isn't it?

Project directory size

Pre-composer days, the size of the project directory used to be very big. We would carry all the libraries that our project depends on and pass around the project either in USB sticks or pollute the VCS (git) history.

Enter Composer - Size reduces to less than 20%? We can get away without keeping the dependencies in the project (.gitignore) and avoid version mismatches at the same time thanks to composer.lock file.

sad fact - Codeigniter 3 still uses the traditional download system.

Hours of debugging

The libraries or frameworks that your project uses depend on some other libraries (and the chain continues...). Possibly, the framework is using version X of a library while another library is using version Y of the same library.

You have been getting errors due to some clash or incompatibilty and have to put a lot of time to get to the base of the issue. No more - composer keeps only one copy of a library with a suitable version or denies the installation request.

Autoloading

Remember that long list require statements? As the project grows in size, so does the number of files we need to include in each of the file. PHP autoloading came to the rescue but still it was comparatively hard to setup and maintain as dependencies grow. Less discussed powerful feature of Composer is Autoloading. It supports PSR-0, PSR-4, class mapping as well as files autoloading. We need to require just one file and we're done. Play with straightforward namespaces and enjoy the development time.

Less known fact - Composer provides three different levels of autoloader optimisation for your different level of needs.

Lengthy Installation procedures

Often times, one or more steps need to be followed after downloading a library for setup and installation. Package maintainers had to write detailed installation procedures in the documentation and still answer support queries when users won't follow them and then complain about errors. Composer scripts are a boon for them.

One can easily code the steps that can be automated and run as a script during various stages of the package download. For example, Laravel uses composer scripts to create an .env file, create an application key, and perform automatic discovery of the packages.

Platform Requirements

The code of your library/package may support only latest PHP versions or depend on specific PHP extensions. And you can inform Composer about this resulting in prevention of package downloads on the systems that don't meet the requirements. For example,

"require": {
    "php": "^7.1.3",
    "ext-mbstring": "*",
    "ext-openssl": "*",
    ...
},

Add this to your composer.json and composer will throw an error when the systems with PHP less than v7.1.3 or without mbstring and openssl extension try to download the package.

Maintaining a library/package

Package maintainers had to either maintain different directories for each version of the package or release new versions through GitHub everytime there was an important update. Thanks to the graceful integration of Composer with VCS tags and branches, one just needs to add a tag to the commit and push. The rest is taken care of.

Composer highly recommends Semantic Versioning and following that, package maintainers can keep focus on actual development without worrying about the distribution.

Marvellous. I do not have complains any more and am ready to jump in. What next?

Nuts and bolts of Composer

Now that we have an idea about what and why of the Composer. Let's jump into the how part:

Installation

The installation instructions on the composer documentation are pretty clear and I think my best job is to link you there.

Consumption

If you want to build a project using Laravel, you need to install it using composer. Though some people want to go with the traditional way, it is highly discouraged.

Laravel itself uses lots of useful open-source package like PHPUnit, Monolog, Carbon, etc. Those dependencies are also managed by composer. You should learn about version management to avoid potential issues.

Fun Fact - Composer installs dependencies in the vendor directory by default but it also supports custom installers for various package types that can install dependecicies in other directories.

Version management

Understanding how composer downloads the libraries based on the version constraints specified in your composer.json file will help you a long way. I recommend you to go through the original documentation article at least once.

Did you know? - You can require a package by its version, branch or
even by a specific commit SHA (not recommended).

Personally, my suggestion is to use Caret Version Range (^) for the packages which use Semantic versioning and Wildcard Version Range (.*) for others as they are easy to grasp.

Understanding composer.lock file

While composer.json is managed automatically when you use the create-project command or when you directly require a package from the terminal. composer.lock is something you should be aware of.

First of all, you should commit your composer.lock file to make sure that everyone of your team members use the same copy of the dependencies while working on a common project. How does that happen?

Whenever you run composer install, Composer actually checks for the existence of the composer.lock file. If it is present, it installs all the dependencies as per the lock file which contains exact version numbers and SHAs to be used. If lock file is not present, Composer simply reads the composer.json file, installs the dependencies and creates the composer.lock file. Next time you run the install command on server or some other computer, lock file is used to give you the exact same copy.

On the other hand, composer update command looks at the composer.json file directly, installs the new versions of the dependencies, if available, as per the version contstraints and updates the lock file.

Slowness of Composer

I have experienced slow installs and updates by composer. Unknown about what's going on in the background, I would just keep staring at the screen as I wait for it to complete before I can take my next step.

If you're facing the same issue, I suggest you to append the composer command with --profile and -vv or even -vvv to have more information about background processing. For example,

composer install -vv --profile

If you cannot find any specific issue from the output, you can also try this package to enable parallel downloads.

Package development

If are just starting out building your first package/library, there is a very useful tip to make the development easy and comfortable.

Most of the times, the package/library needs to be tested against an actual project during development and for that - maintainer may need to keep the package inside the actual project to avoid unnecessary multiple releases until he's done.

Composer Path repositories can save yourself from that trap. It will Symlink or Mirror the repo in the project and you can keep the code bases separate and manage and switch them easily.

Laravel super artisan Caleb Porzio even added a bash alias to use this feature with a single command.

Quick tip - If your package contains a command line script which you would like to pass along to the users, consider using vendor binaries. PHPUnit uses it to quickly let you fire vendor/bin/phpunit.

Branch Aliasis

Once your package/library is already being used by multiple projects, you should also consider adding branch aliasis to make developers' life a bit easier. This article explains the reason behind it very well and also specifies how to do it.

Advanced level developers - Composer allows you to alter or expand it's functionality by using composer-plugins. You can perform actions when your package is loaded and when certain events are fired.

Final notes

This was a bit longer one. We covered quick history about dependency management, learned what Composer is, discussed about the pains that it fixes and then went through some useful points and tips around composer for the new developers and package maintainers.

That is pretty much what I had to say. If you've reached here all the way from the top reading each line, thank you. I think our thinking style matches. Say hi in the comment section below.

If you have any questions, feel free to post your comment, I would try my best to solve your queries.

And If you think this can help other developers in your online network, I’d be happy to see you sharing this with them. Thanks.

Step by step guide to Laravel package development

Gaurav Makhecha — Fri, 25 May 2018 13:20:55 +0000

Are you curious how open-source Laravel packages are developed from scratch? Or are you unsure whether any specific functionality makes a good use case to be a Laravel package?

Let’s talk about these and other related questions today.

We all are fans of Laravel and its ecosystem for its simplicity and extensibility. Packages have been playing a major role in moving it forward. Especially official packages by Laravel, Spatie , Barry vd. , and others have made our lives and code better.

Why you should build a Laravel Package

Better coding skills

Open-source is magical. Putting your code out into the public makes you a bit vulnerable at the beginning but brings out the best of you. The fear of doing something wrong prevents every bit of you from doing the git push origin master but it’s always worth it. Laracasts’ series on open source project management can help a lot if you’re not well-versed with GitHub.

More (and better) work

You will build you brand leading to more work.

"Talk is cheap. Show me the code." - Linus Torvalds (creator of Linux and Git)

As developers and clients see your code and benefit from it, you will get more recognition.

Save time

You will save yourself considerable amount of time when you convert a piece of code, that you are using in more than one projects, into a package. “DRY” approach isn’t a new thing. We know its benefits.

In short, open-source package development makes your developer life better.

Now that we have a better idea about the need to go ahead with package development, let’s make one together now.

On a side note, contributing to an existing solution is also a great way to start if there is already an open-source package/library of your choice.

A new Laravel package from scratch

Note: I had said we will be building a real package. While thinking about an example, the only good option I could come up with was one of my own packages - Laravel Log Enhancer. It is short enough to cover quickly as well as plays with important parts of package development to learn the basics properly.

If you haven’t created any Laravel package before, I insist you to do this with me. It’ll be fun. Even if you make the same package, you’ll have more confidence and will be inspired to make changes or create a new one instantly. All the steps are undoable - you’ve nothing to lose. And true learning is all about doing the things practically. Our requirements are basic. If you’re already running any Laravel app locally, you’ve it all.

Let’s start.

1. New package directory

Create a directory with a name of the package. I will call it laravel-log-enhancer.

mkdir laravel-log-enhancer && cd laravel-log-enhancer

2. Love for git

Initialize a git repository. We’ll need GitHub repo to put the package online.

git init

3. composer.json

Every package starts with a composer.json file. Let’s create it. The easiest way to create it is to fire the init command.

composer init

Or you can just copy it from this stub and make changes accordingly.

Commit the change. Not compulsory but we will do it after each unique step as a good habit.

4. Namespace and autoloading

We will put the main code of our package in src directory.

mkdir src && cd src

By the way, just like Laravel web app development, there are no hard rules about directory structure here but a helpful convention to follow.

We will update our composer.json file for 2 important things.

When a Laravel project uses our package, we can inform it about the location of the files of the package to be loaded by putting the path in PSR-4 autoloading part of composer.json.
To make the installation easy for the developer, we will put the location of the service provider, that should be automatically detected by Laravel, in extra section of the file.

...
"autoload": {
    "psr-4": {
        "Freshbitsweb\\LaravelLogEnhancer\\": "src/"
    }
},
"extra": {
    "laravel": {
        "providers": [
            "Freshbitsweb\\LaravelLogEnhancer\\LaravelLogEnhancerServiceProvider"
        ]
    }
}
...

By autoload, the parent Laravel web app knows about our base namespace i.e. Freshbitsweb\LaravelLogEnhancer and the files location which is the src directory. And Laravel’s awesome package discovery feature helps us remove a step from package installation process.

5. The service provider dilemma:

Many beginners stuck at this stage. Don’t worry. Let’s try to simplify this. A service provider is a file that can tell the parent Laravel application about various offerings of the package.

Common belief is that we always need a service provider for a package. That’s not the case. If your package doesn’t need to autoload any resources in advance, it can skip the service provider. But in most of the cases, for a package to be useful enough, service provider is required.

We will use it in our case to load the default configuration options of the package as well as offer an option to export those config options to the parent Laravel web app.

<?php

namespace Freshbitsweb\LaravelLogEnhancer;

use Illuminate\Support\ServiceProvider;

class LaravelLogEnhancerServiceProvider extends ServiceProvider
{
    /**
     * Publishes configuration file.
     *
     * @return  void
     */
    public function boot()
    {
        $this->publishes([
            __DIR__.'/../config/laravel_log_enhancer.php' => config_path('laravel_log_enhancer.php'),
        ], 'laravel-log-enhancer-config');
    }

    /**
     * Make config publishment optional by merging the config from the package.
     *
     * @return  void
     */
    public function register()
    {
        $this->mergeConfigFrom(
            __DIR__.'/../config/laravel_log_enhancer.php',
            'laravel_log_enhancer'
        );
    }
}

The code is quite simple here. In the boot method, we put the code to allow the developer to export the config options by simply writing:

php artisan vendor:publish -tag=laravel-log-enhancer-config

And in the register method, we tell the Laravel app to add the config options from our file into the web app config. Commit the update and let’s create our config file next.

6. Config options:

As a part of the convention, we will put our config file in config directory inside root folder next to src directory.

mkdir config && cd config && touch laravel_log_enhancer.php

Put the following code in the file.

<?php

return [
    'log_request_details' => true,

    'log_input_data' => true,

    'log_request_headers' => false,

    'log_session_data' => true,

    'log_memory_usage' => false,

    'log_git_data' => false,

    // You can specify the inputs from the user that should not be logged
    'ignore_input_fields' => ['password', 'confirm_password'],
];

This file contains few configuration options just like a regular Laravel config file. Commit.

7. Package classes

Final piece of code, for actual enhancement of Laravel logs, is the LogEnhancer.php file. To keep the length of the article digestible, I will directly link you to the actual class that you can copy. We also have RequestDataProcessor.php in the package. Put both of them in the src directory and you should be good to go.

8. Other important files

There are few other files that we need to add finally.

README file needs a special mention here. It is the face of the package. You should be writing detailed installation steps and other notes with proper flow in this file. Go through this GitHub guide for more.

Commit this change and now our package is ready to use.

What next? It’s time to release it.

How to release the package

If you haven’t pushed the package code to GitHub, do it first. If you don’t know how, this article can help.

Then, head over to Packagist , create an account or sign in, Click on Submit, specify the GitHub repo URL, … Steps are quite easy and self-explanatory. You should also enable Auto update of the package and consider Semantic versioning and releasing .

Congrats. We’re done. Breath for a few minutes. There’s more.

Next, there are many other things are not part of the package development but are important for the development lifecycle and maintenance. Let’s go through them quickly.

How to use the package locally

We don’t have to push the updates online before testing it locally. Composer repositories path to the rescue.

Not just the package, we can do it with any repository. Here’s a great article explaining the details.

Let’s do it. Install a fresh Laravel app next to your package directory.

laravel new laravel-with-package

Make changes in it’s composer.json file

...
"repositories": [
    {
        "type": "path",
        "url": "../laravel-log-enhancer"
    }
],
...

Install the package by firing the following command.

composer require gauravmak/laravel-log-enhancer

Complete the installation steps and you can use the package now.

Testing

“I find that weeks of coding and testing can save me hours of planning.” -
Unknown

They say - do not use a package without tests. They’re right. As the package gets bigger in size and more contributors enter the scene, some random commit can break the code functionality somewhere down the line. And we never want it to happen, right?

And it’ not hard. All we need to do it to check if the package is doing what it is supposed to do after every change/commit. In this package, we are adding processors to the Monolog handlers so that more data can be logged.

Unfortunately, as of now, Monolog doesn’t provide a method to fetch the processors of a handler so we are limited but let’s create a base of the testing for this package so that you know how to add tests to your custom package.

To start, we will add requirements to the composer.json file.

...
"require-dev": {
    "phpunit/phpunit": "^7.0",
    "orchestra/testbench": "~3.6.0"
 },
 "autoload-dev": {
    "psr-4": {
        "Freshbitsweb\\LaravelLogEnhancer\\Test\\": "tests"
    }
 },
 ...

We are basically testing a package which is outside a Laravel app. orchestral/testbench is a great package which can add the necessary dependencies so that we can test it as if we have all the Laravel goodies.

I have also added the following files to make the base of testing for our app.

Go through the README file of the testbench package for all details about how we can interact with Laravel while testing our package.

Integrations

There are so many helpful tools that integrate with GitHub repo and help us maintain the packages/libraries easily.

I suggest Travis CI for testing the package after each update and StyleCI for maintaing the code style.

I have integrated StyleCI in the package already. You should also consider adding badges to the README file.

Secret sauce of a successful package

You reap the benefits of making the package when more and more developers use it. And for that, there are so many factors starting from the basic idea behind the package to the stability and age of the package (stars).

If I were to decide on most important point for that, it would be the developer friendliness of the package. Yes, the exact reason why Laravel is popular.

Try to minimize the installation steps and the code that is required to use the package. Plus, it has to be readable enough that it doen’t need to annotated with long comments.

For example,

$users = User::with('roles')->get();

So simple, we know this operation involves join queries and other stuff. Still, you like to write it and read it. Do things on a similar level.

Final notes

That’s it for the day. We learned why package development is good for everyone and how to do it step-by-step using a real example. If you have any questions or get stuck anywhere, just add a comment below, I would be happy to help.

And If you think this can help other Laravel developers in your online network, I’d be happy to see you sharing this with them. Thanks.

Time-saving habits for programmers

Gaurav Makhecha — Thu, 26 Apr 2018 14:10:00 +0000

"I wish there were more than 24 hours in a day to let me achieve more."

Have you ever desired to have more time available for completing your side-projects or meeting the deadline, just like me?

Both of us know there cannot be more than 24 hours a day; the Better choice is to just use the time that we have in the most efficient way.

There are many habits that help programmers perform better and leverage limited time. There are no shortcuts. It is all about good habits. Once formed, they can save a ton of time for you. Let's cover some of those habits very quickly.

1. Time tracking earns

Do you know how many minutes do you take to complete the X task? And how much of your work time is actually invested in developing stuff? 80%? 70? Way less than you think it is if you’re not tracking time currently. What about your team? How many hours do they code every working day?

It is very important to measure each of your activities on a day-to-day basis. Only then you can provide estimates for future projects properly.

"When work time is tracked, efficiency improves. And when the tracked time is being reported, speed of efficiency improvement doubles."

Fruits of this habit are way beyond statistics.

You can use any of the available time tracking tools . Toggl has served me well for a few years now and I cannot recommend it enough.

2. Distraction-free workspace

Every now and then, we read articles on the 21st-century gadgets distracting us every few minutes. The benefit of technology advancements is that we have easy access to an ocean of knowledge now

But, too many attention seekers in today’s social world are breaking our workflow. Focus is more important than information, talent or intelligence.

A practical tip would be to keep your phone away while working and turning off all those notifications to improve your focus and concentration. Using good quality headphones or ear plugs for noise cancellation is a no-brainer

I have used Pomodoro technique myself and it has helped me stay focused a lot. Constraints bring creativity. Try it. There are many regular practitioners of Getting Things Done as well.

3. Pair Programming

I have been enjoying the fruits of this habit recently. You might say: "How can the time be saved if 2 people are working on a single task together?" I had the exact same question before.

Still, to give it a try, I started coding the system for this site with a teammate and there are more PROs to this method than CONs. We could decide on the system architecture pretty quickly, solve issues faster and the main benefit was that both of us were quite focused.

Our mind is constantly wandering but when there is someone watching you during the coding sessions, the peer pressure keeps your concentration intact. And that is why live streaming of coding sessions is getting popular as people are seeing the advantages of it.

Note: Pair programming may not help in all cases. Firstly, both the developers should be on a somewhat similar experience level. Maximum time is saved when the project involves complex logic and updates. I would just say - try and see if it works in your case.

4. Energy management for good mood

A programmer’s work is completely a mind game. Only a sound mind can effectively achieve desired outcomes. Every one of us experiences flow in work occasionally and wish to have it every time we sit in front of the computer, isn’t it so? And for that, we need to train our minds. It's all about energy.

Every decision you make throughout the day uses energy and brings fatigue. Be a morning person. Most of us have a vibrant mind in the morning time. (I know, few owls!..) Observe your mood timings. When do you perform at a very low level? And when is the peak? Build a great routine around it and energy will flow throughout the day.

5. Divide and conquer

Just like we take our meal ‘bite’ wise, our work assignments need to be completed in steps too. Whenever you are about to start a task, the first step would be to break it down into smaller logical pieces and execute them one-by-one. You would assign a specific time to each task using the methods discussed above.

If not, you would, like I do many times, be staring at the screen, thinking about various future problems and their solutions for a couple of hours. No work is done. Dividing the task into easy-to-digest pieces/sprints saves time.

And this habit is connected with one very important point - No Multi-Tasking. I can’t recommend this enough. There would be thousands of articles throwing light on this single term especially. Doing several tasks at a time is a badge of pride for many of us; it is one of the biggest barriers to higher productivity at the same time. Our mind is designed to do only one task very effectively. You may try both ways and measure the results yourself.

6. Take a Break, buddy!

Now that we have loaded our minds with lots of information and processed so many thoughts, let's talk about breaks. Standing up periodically is required for "office workers" to prevent backaches.

And just like your body, your mind needs rest as well. As we know, muscles do not grow while one is working out at the gym; They get stronger during the relaxation phase instead. The same is true for the brain. Let it repair and restore the parts after a heavy dose of work. In fact, we often get solutions to our problems during our leisure time.

This habit can save time in 2 ways:

By doing some stretches during a break will lead to a healthy body. And yeah, we add lots of hours to our life span with that
Let me illustrate with an example:

4:40 PM: You have been trying to troubleshoot a complex bug for 40 mins and still nowhere.

4:45 PM: You decide to take a 5-min break finally to give it a last chance before you have to leave at 5.

4:55 PM: 5 minutes after returning from a break, you have solved it. Bingo!

7. Practice-clad foundation

"The only way to learn a new programming language is by writing programs in it."Dennis Ritchie

This is the most common advice while learning a new language and probably the least followed one as well. In today’s world, we love everything to be fast; Be it cars, computers, or mobiles. At the same time, our learning is becoming rapid day by day.

We like to just skim through the articles (if you read this, you are not skimming, cheers), documentations and videos when we are learning something new. While this is helpful in a few cases, detailed learning is hardly exercised. Simply put, do _sample projects_repeatedly when you learn new tools/frameworks to master them.

At the same time, practice and mistakes go hand in hand. Never let the fear of mistakes stop you from acting. While acquiring knowledge, the more mistakes you make, the quicker you become adept at the respective skills. Mistakes while learning is good.

A proper foundation of logic and programming lets you complete a project in half the time others take. The 10,000 hours rule does have essence I believe.

8. Code quality

In programming, there is no right way to do things. Every style is opinionated. You just have to pick one that suits yours and follow it. At the end of the day, the code should be Readable, Maintainable, Well-tested, and Well-documented.

This will save time in the future. Software is never done. There are constant bug fixes, features additions, and requirements updates. If the code is readable enough, you can make the changes quickly. A maintainable code will be easy to approach while adding new functionalities. A well-tested one will boost your confidence and avoid the worries of domain-level effects during code updates.

9. Forget office politics

Finally, this habit is going to take you to higher levels in the long run. We get into the competition with co-workers, unconsciously sometimes. This wastes a lot of time. We throw away more energy while trying to win the game instead of focusing on actual work.

The other benefit of ‘being’ together is long-term growth. Sharing is caring. When ‘I’ becomes ‘We’, each person of the group excels gradually.

"If you want to walk fast, walk alone. But if you want to walk far, walk together."Ratan Tata

Just like savings, working as a team is hard at first and very fruitful eventually. Try that and you will never regret it.

That's it!

These are important points, among others, which can help us achieve our goals. I would appreciate you sharing them with others. You are welcome to share your tips below in the comments section. Thank you.