DEV Community: Daniel Werner

How to implement translations with JetStream, Intertia and Vue3 using Laravel 10

Daniel Werner — Tue, 15 Aug 2023 16:00:05 +0000

Laravel 10 comes with internationalization support out of the box, however when we use JetStream starter pack with Inertia the transaction support is not included in the Vue part. Luckily it is quite easy to make it work.

Our use case

A brand new Laravel 10 application, using JetStream with Intertia and Vue3 frontend. The app requires multilanguage support, so we need a solution that we can use in both frontend and backend code. The best would be to use the same language files for both. In the newest Laravel (in time of writing it is version 10) we can use both json files and php files for translations. The php files are located in lang/{locale}/file.php. These files can be separated by "topic" like auth, validation etc. In case of json files, we only have one file per locale, and they are located in resources/lang/{locale}.json We want to use the latter because it is easily to pass the values to the frontend in json format.

Default Laravel translation keys in json

Laravel has a built in command to publish the default language files: php artisan lang:publish ** Unfortunately this only publishes the php language files. To convert them to json I used a quick and dirty solution and replaced the return in those files by using **echo json_encode(['translation' => 'content']), and copied over the json. One caveat here is that the php file name is the translation prefix (for example auth), so in the json you need to add auth. prefix to all the translation keys (for example: auth.password ).

Share the translation data from the backend

To be able to use the same language pack in both the frontend and the backend, we need pass the translation data to the frontend. First create a helper function which reads the json file support/helpers.php :


<?php

if (! function_exists('translations')) {
    function translations($json)
    {
        if (!file_exists($json)) {
            return [];
        }

        return json_decode(file_get_contents($json), true);
    }
}

Add this file to the composer json autoload and run composer dump-autoload :


    "autoload": {
        "files": [
            "support/helpers.php"
        ],

We use Inertia so we share the translation object from the json by adding the following to the app/Http/Middleware/HandleInertiaRequests.php middleware:


   public function share(Request $request): array
    {
        return array_merge(parent::share($request), [
            'locale' => function () {
                return app()->getLocale();
            },
            'translations' => function () {
                return translations(
                    resource_path('lang/'. app()->getLocale() .'.json')
                );
            },
        ]);
    }

This makes the translations available as Inertia props.

Create Vue3 plugin for translation

The localization needs to be accessible everywhere so we create a plugin and make it accessible globally. Create a file resources/js/Translator.js


export const Translator = {
    install: (v, translations) => {
        v.config.globalProperties.__ = function(key, replace = {}) {
            let translation = translations[key]
                ? translations[key]
                : key;

            Object.keys(replace).forEach(function (key) {
                translation = translation.replaceAll(':' + key, replace[key])
            });

            return translation
        };
    },
};

This basically finds the given key in the translations object and replace the placeholders in the translation if there is any. We make our function " __" available globally by adding it to the *globalProperties. *

For further details about Vue plugin development check out the docs here: https://vuejs.org/guide/reusability/plugins.html#writing-a-plugin

Now our plugin is ready, let's use it in our app: resources/js/app.js


import './bootstrap';
import '../css/app.css';

import { createApp, h } from 'vue';
import { createInertiaApp } from '@inertiajs/vue3';
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers';
import { ZiggyVue } from '../../vendor/tightenco/ziggy/dist/vue.m';
import {Translator} from './Translator.js';

const appName = import.meta.env.VITE_APP_NAME || 'Laravel';

createInertiaApp({
    title: (title) => `${title} - ${appName}`,
    resolve: (name) => resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**/*.vue')),
    setup({ el, App, props, plugin }) {

        return createApp({ render: () => h(App, props) })
            .use(plugin)
            .use(ZiggyVue, Ziggy)
            .use(Translator, props.initialPage.props.translations)
            .mount(el);
    },
    progress: {
        color: '#4B5563',
    },
});

Using translations

In blade files you can use the __() function as usual in Laravel, it will automatically find the proper json language file according to the app current locale. In Vue components use the same function like this:


<p>{{__('auth.failed')}}</p>

When using options API you can use it in the code like: this.__('auth.failed').

Useful resources

I'd like to thank Dario Trbovic I took the original idea from his blog post: https://dariot.medium.com/how-to-translate-laravel-with-inertia-c34c7284544e.

Vue3 documentation about writing plugins: https://vuejs.org/guide/reusability/plugins.html#writing-a-plugin

Laravel documentation about localization: https://laravel.com/docs/10.x/localization

Planning poker app - a journey from Vue.js to Express through Socket.IO

Daniel Werner — Mon, 29 May 2023 07:51:12 +0000

In agile development process it is common to use planning poker to determine the story point of the tickets. There are plenty of free planning poker apps out there, but while using those we usually had some trouble with them. Either it cannot create a new game, or it just freezed and cannot restart, or any other. What every developer thinks in these cases? Let's build our own app, it is simple. Well, yeah, kind of... :)

How it should work?

For the MVP we looked for the basic functionality:

A user creates a new game, and becomes an admin in that game
Sharing the game url so the other players can join the game
Every player gets a card where the points will appear
Use fibonacci numbers for the possible points
The admin has the ability to reveal the cards and start a new round
When the cards are revealed it is not possible to change the points anymore
The process should be interactive, every change should appear immediately for all the players

Which stack to use?

The obvious choise for the frontend was Vue.js. I am using it on daily basis, and used in many projects before

For the interactivity we need websockets, thus the choice was Socket.IO, because it is a mature enough, battle tested library.

The backend uses Express.js server

How it was built?

First step was to create a new Vue.js app with npm cli:

npm init vue@latest

Install Express:

npm install express

Install Socket.IO

npm install socket.io

Using a single file for the backend stuff: express.js. We use vue router and have 3 routes to hanle: the main route (/), the game route (/game/hashid), and an about page (/about). The goal is to serve both the app and the socketio server on the same domain, we tell express to serve the vue app from public directory for both routes:


app.use('/', express.static('public'));
app.use('/game/:id', express.static('public'));
app.use('/about', express.static('public'));

We define a route in express and handle the new game generation, it generates a new uid for the game, store it in an object and return the id to the frontend. We also store the admin_id of the player who created the game.


app.post('/generate', (req, res) => {
    const id = uid(16);

    games[id] = {
        admin_id: req.body.player_id,
        players: {}
    };

    res.send({id: id});
});

The next step is to handle the connection of the players. We check if the game_id exists, and add the player to the games object. If the admin has joined we return isAdmin: true , to let the frontend know that the current player is an admin, and show them the reveal and reset buttons.


io.on('connection', (socket) => {
    let game_id = socket.handshake.auth.game_id;

    if(!games.hasOwnProperty(game_id)) {
        socket.disconnect();
        return;
    }

    let currentGame = games[game_id];

    socket.join(socket.handshake.auth.game_id);
    io.to(game_id).emit("players", currentGame.players);

    socket.on('join', (data, callback) => {
        let name = data.name,
            player_id = socket.handshake.auth.player_id;

        games[game_id].players[player_id] = {player_id: player_id, name: name, points: null};
        io.to(game_id).emit("players", currentGame.players);

        callback({
            isAdmin: socket.handshake.auth.player_id === games[game_id].admin_id
        });
    });

The next event we want to handle is when the players choose points. We find the user who sent the points, set the points to that user, and emit the whole players object to all the connected players.


socket.on("points", (...args) => {
    let data = args.pop();
    games[game_id].players[socket.handshake.auth.player_id].points = data.points;
    io.to(game_id).emit("players", currentGame.players);
});

We reached to the admin events, reveal and reset. In both cases we ensure that the event has come from the admin. Reveal is quite simple only sending the reveal event, and all the clients will show the point of the players:


socket.on("reveal", (...args) => {
    if(games[game_id].admin_id === socket.handshake.auth.player_id) {
        io.to(game_id).emit("reveal");
    }
});

In the reset we delete the points of the users, send the reset and players events to the clients:


socket.on("reset", (...args) => {
    if(games[game_id].admin_id === socket.handshake.auth.player_id) {
        currentGame = games[game_id];

        for (let key in currentGame.players) {
            currentGame.players[key].points = null;
        }

        games[game_id] = currentGame;

        io.to(game_id).emit("reset");
        io.to(game_id).emit("players", currentGame.players);
    }
});

The last but not least thing to handle is the disconnect event, where we remove the disconnected player for the data, and let everyone know that we don't have that player anymore:


socket.on('disconnect', () => {
    socket.leave(socket.handshake.auth.game_id);
    delete games[socket.handshake.auth.game_id].players[socket.handshake.auth.player_id];
    io.to(game_id).emit("players", games[socket.handshake.auth.game_id].players);
});

With this we finished the server part, let's take a look at some interesting parts of the frontend. I don't want to bore the reader with all the details of the desing and html, we'll just focus on the socket communication.

Let's create a socket.js where we create a state to store all the game related data:


import { reactive } from "vue";
import { io } from "socket.io-client";

export const state = reactive({
    connected: false,
    greetEvents: [],
    players: {},
    isAdmin: false,
    game: {
        status: null
    }
});

export const socket = io('/', {autoConnect: false});

socket.on("connect", () => {
    state.connected = true;
});

socket.on("disconnect", () => {
    state.connected = false;
});

socket.on("players", (...args) => {
    state.players = args.pop();
});

When the player opens the home page, and starts a new game, we send and ajax request to the backend and if it was successfull, redirect the user to the game page.


generateGame() {
    if (!this.player_id) {
        this.player_id = uid(16);
    }

    axios.post('/generate', {
        player_id: this.player_id
    }).then(
        (response) => {
            console.log(response)
            this.url = '/game/'+response.data.id;
            sessionStorage.setItem(response.data.id + '_player_id', this.player_id);
            state.isAdmin = true;
            this.$router.push('/game/'+response.data.id);
        });
}

After this step a modal appears and the player can fill in their name and connect to the game. This step is handled in the mounted hook of the vue component. To prevent losing the active game when reloading the page, we store the player_id for the active game in the session storage, and use it to connect to the game if present (if a page reload happens).


mounted() {

    this.game_id = this.$route.params.id;

    this.selectBonusPoint();

    this.player_id = sessionStorage.getItem(this.game_id + '_player_id');

    if (sessionStorage.getItem(this.game_id + '_player_name')) {

        this.name = sessionStorage.getItem(this.game_id + '_player_name');

    }

    if (!this.player_id) {

        this.player_id = uid(16);

        sessionStorage.setItem(this.game_id + '_player_id', this.player_id);

    }

    socket.auth = {

        game_id: this.$route.params.id,

        player_id: this.player_id

    };

    socket.connect();

    if (this.name) {

        this.joinGame();

    } else {

        this.showModal = true;

    }

}

Before we finish our journey let's check the join game method, which will send the payer's name to the backend to show up on the players card. This is the point where we receive and store the isAdmin property to determine if our user is admin in the current game:


joinGame() {
    socket.emit('join', {
        name: this.name
    }, (response) => {
        state.isAdmin = response.isAdmin
    });

    sessionStorage.setItem(this.game_id + '_player_name', this.name);
}

Conclusion

This was my very first time playing with Socket.IO and the Express framework. I had fun developing this project, and I see a lot of possibilities using this technology for the future projects as well. If you are interested in the source code, it is open source you can find it here: https://github.com/wdev-rs/planningpoker.

Package development in Laravel - meetup with video

Daniel Werner — Mon, 15 May 2023 10:06:39 +0000

We've organized a meetup in WDev office on the topic of pakcage development in Laravel. We had great time exploring the following topics:

WHAT are PHP packages
WHY should we create packages?
HOW to start?
Versioning packages
Usage with composer
Laravel specific packages
Developing Laravel packages
Live coding examples

If you are interested find the recording of the event here:

Laravel analytics - how and why I made my own analytics package

Daniel Werner — Wed, 26 Apr 2023 19:36:37 +0000

I've used google analytics for couple of years and it worked quite well for me. The question arises why did I make my own analytics package. There were a couple of reasons to do so:

Google analytics became quite complex and slow lately. Especially with introduction of the new Google Analytics 4 it became more complex, and I realised that I don't use even 0.1 percent of its capability. This blog and the other websites I developed as side projects only need simple things like visitor count per day in a specific period, and page views for the top visited pages. That's it!
I wanted to get rid of the third party cookies as much as possible
Third party analytics tools are mostly blocked by ad blockers, so I see lower numbers than the real visitors.

Requirements

It needs to be a Laravel package, as I want to use it in couple of projects
Keep it simple, only the basic functionality
- Track page visits by uri, and also the relevant model ids if applicable (for example blog post id, or product id)
- Save UserAgents for possible further analysis of visitor devices (desktop vs mobile) and to filter out bot traffic
- Save IP address for a planned feature: segment users by countries and cities
- "In house" solution, track the data in the applications own database
- Only backend functionality for tracking, no frontend tracking
- Create chart for visitors in the last 28 days, and most visited pages in the same period
Build the MVP and push back any optional features, like
- Aggregate the data into separate table instead of querying the page_views table (I'll build it when the queries become slow)
- Add geoip databse, and save the user's country and city based on their IP
- Add possibility to change the time period shown on the charts

The database

As I mentioned earlier the goal was to keep the whole thing very simple, so the database only consits of one table called laravel_analytics_page_views where the larave_analytics_ prefix is configurable in the config file to prevent potential conflicts with the app's databses tables.

The schema structure/migration looks like this:


$tableName = config('laravel-analytics.db_prefix') . 'page_views';

Schema::create($tableName, function (Blueprint $table) {
    $table->id();
    $table->string('session_id')->index();
    $table->string('path')->index();
    $table->string('user_agent')->nullable();
    $table->string('ip')->nullable();
    $table->string('referer')->nullable()->index();
    $table->string('county')->nullable()->index();
    $table->string('city')->nullable();
    $table->string('page_model_type')->nullable();
    $table->string('page_model_id')->nullable();
    $table->timestamp('created_at')->nullable()->index();
    $table->timestamp('updated_at')->nullable();

    $table->index(['page_model_type', 'page_model_id']);
});

We track the unique visitors by session_id, which is of course not perfect and not 100% accurate but it does the job.

We create a polymorpthic relation with page_model_type and page_model_id if there is a relevant model to the tracked page we save the type and the id to use in the future if necessary. Also created a combined index for these 2 fiels, as they are mostly queried together when using polymorphic relations.

The middleware

I wanted and universal solution rather than adding the analytics to all the controllers created a middleware which can handle the tracking. The middleware can be added to all routes or to specific group(s) of routes.

The middleware itself is quite simple, it tracks only the get requests and skips the ajax calls. As it doesn't make sense to track bot traffic, I used the https://github.com/JayBizzle/Crawler-Detect package to detect the crawlers and bots. When a crawler is detected it simply skips the tracking, this way we can avoid having useless data in the table.

It was somewhat tricky how to get the associated model for the url in an universal way. The solution at the end is not totally universal because it assumes that the app uses route model binding and assumes that the first binding is relevant to that page. Again it is not perfect but it fits the minimalistic approach I followed while developing this package.

Here is the code of the middleware:


public function handle(Request $request, Closure $next)
{
    $response = $next($request);

    try {
        if (!$request->isMethod('GET')) {
            return $response;
        }

        if ($request->isJson()) {
            return $response;
        }

        $userAgent = $request->userAgent();

        if (is_null($userAgent)) {
            return $response;
        }

        /** @var CrawlerDetect $crawlerDetect */
        $crawlerDetect = app(CrawlerDetect::class);

        if ($crawlerDetect->isCrawler($userAgent)) {
            return $response;
        }

        /** @var PageView $pageView */
        $pageView = PageView::make([
            'session_id' => session()->getId(),
            'path' => $request->path(),
            'user_agent' => Str::substr($userAgent, 0, 255),
            'ip' => $request->ip(),
            'referer' => $request->headers->get('referer'),
        ]);

        $parameters = $request->route()?->parameters();
        $model = null;

        if (!is_null($parameters)) {
            $model = reset($parameters);
        }

        if (is_a($model, Model::class)) {
            $pageView->pageModel()->associate($model);
        }

        $pageView->save();

        return $response;
    } catch (Throwable $e) {
        report($e);
        return $response;
    }
}

The routes

When developing Laravel packages it is possible to set up the package service provider to tell the application to use the routes from the package. I usually don't use this approach, because this way in the application you don't have much control over the routes: for example you cannot add prefix, put them in an group or add middleware to them.

I like to create a class with a static method routes, where I define all the routes.


public static function routes()
{

    Route::get(
        'analytics/page-views-per-days',
        [AnalyticsController::class, 'getPageViewsPerDays']
    );

    Route::get(
        'analytics/page-views-per-path',
        [AnalyticsController::class, 'getPageViewsPerPaths']
    );
}

This way I could easily put the package routes under the /admin part in my application for example.

The frontend components

The frontend part consists of 2 vue components one for the visitor chart and one contains a simple table of the most visited pages. For the chart I used the Vue chartjs library (https://github.com/apertureless/vue-chartjs)





<template>
    <div>
        <div><strong>Visitors: {{chartData.datasets[0].data.reduce((a, b) => a + b, 0)}}</strong></div>
        <div>
            <LineChartGenerator
                :chart-options="chartOptions"
                :chart-data="chartData"
                :chart-id="chartId"
                :dataset-id-key="datasetIdKey"
                :plugins="plugins"
                :css-classes="cssClasses"
                :styles="styles"
                :width="width"
                :height="height"
            />
        </div>
    </div>
</template>

<script>

import { Line as LineChartGenerator } from 'vue-chartjs/legacy'
import {
    Chart as ChartJS,
    Title,
    Tooltip,
    Legend,
    LineElement,
    LinearScale,
    CategoryScale,
    PointElement
} from 'chart.js'

ChartJS.register(
    Title,
    Tooltip,
    Legend,
    LineElement,
    LinearScale,
    CategoryScale,
    PointElement
)

export default {
    name: 'VisitorsPerDays',
    components: { LineChartGenerator },
    props: {
        'initialData': Object,
        'baseUrl': String,
        chartId: {
            type: String,
            default: 'line-chart'
        },
        datasetIdKey: {
            type: String,
            default: 'label'
        },
        width: {
            type: Number,
            default: 400
        },
        height: {
            type: Number,
            default: 400
        },
        cssClasses: {
            default: '',
            type: String
        },
        styles: {
            type: Object,
            default: () => {}
        },
        plugins: {
            type: Array,
            default: () => []
        }
    },
    data() {
        return {
            chartData: {
                labels: Object.keys(this.initialData),
                datasets: [
                    {
                        label: 'Visitors',
                        backgroundColor: '#f87979',
                        data: Object.values(this.initialData)
                    }
                ]
            },
            chartOptions: {
                responsive: true,
                maintainAspectRatio: false,
                scales: {
                    y: {
                        ticks: {
                            precision: 0
                        }
                    }
                }
            }
        }
    },
    mounted() {
    },

    methods: {

    },
}
</script>

Conclusion

It was quite fun and interesting project and after using it for about an month and analysing the results, it seem to be working fine. If you are interested in the code, or would like to try the package feel free to check it out on GitHub here: https://github.com/wdev-rs/laravel-analytics

Let's do TDD (with video)

Daniel Werner — Wed, 23 Nov 2022 19:00:00 +0000

I am a big fan of Test Driven Development and trying to promote it on every possible occassion. I am doing it because having a good test suite makes me confortable when refactoring or making changes in my code. Also it saved me a couple of times from creating a hidden bug while implementing or changing something.

In this blog post I'll guide you through the process how to start with TDD in any PHP project, how to install phpunit, and even how to make it fun. But let's start with a short introduction about the test driven development.

TLDR;

If you prefer video content scroll down to the bottom, there is a recording from a meetup, where I held a talk about this topic, or just click here to watch it.

Why developers don't write tests?

We don't have time for it

That is the most common escuse for not writing tests. I can understand the time concern. Developers are usually under time pressure, and don't want to waste more time than necessary for a feature. But. You still have to think about the feature before you start implementing it, right? So while thinkig you could also write down your thoughts in a test. I admit you need some experience to quickly write the test cases, and in the beginning it will take some time. In my oppinion it still worth it. Every new thing you learn takes some time.

It is complicated

Yes, it might be. For the first couple of tests, afterwards it becomes a more streamlined process.

It is boring

Yes, if you:

write the tests after the feature, it is definitely boring.
write it beforehand it is less boring, but still not fun
do real test driven development, it can even be fun. I'll show you that later.

I already tested it manually

Yes, we all do. And it is still necessary, the TDD won't replace all the manual testing. My problem with this approach is: do you test all the other, possibly related features. Do you notice, that while implementing a new feature, you might introduced a bug?

Why do we need tests?

It depends on the situation and the project. Not always necessary. If we make a critical, urgent hotfix. If the feature/fix is so simple that testing would make an unnecessary overhead. Developing a feature that is temporary, or likely to change soon. A feature that is not an important part of the system.

Easy and confident refactoring

Have you been in a situation when all of you knew that a piece of code should be refactored, but everyone was afraid to touch it? I've been there couple of times.

The best thing a about test driven development is that with a good test coverage, refactoring the code becomes easy. When you can rely on your tests, you can confidently refactor the code and assure you don't change the functionality or break something.

Prevent bugs

Many times doing TDD you can think of or find bugs that are edge cases and can not be easily catched by manual testing.

Prevent breaking something else

In bigger systems components can be tied together in mutliple ways. Changing some part of the code might break something else. It is very nice when such things happens the test suite warns you about the mistake, and the broken code doesn't leave your machine, and doesn't create problems in production.

Test cases are reproducible

And last but not least, test cases are reproducible. You can run them as many times you want (best to run it on a CI). Who wants to test manually all the features of a web app after each push? No, I really don't :-)

Ok, but what kind of tests?

Unit tests

As the name suggests they are meant to test a small piece of code (units), for example a class or a function. Their advantage is that the are fast, and cheap (in terms of CI running time). As you can see from the testing pyramid below, they are at the bottom, we should have a lot of them :-)

Integration tests

They are made to test some functionality of the app. For example test an api endpoint, or a controller action. They usually need database (or a fake/test database) and are more slow and expensive that unit tests. They should be responsible to assure the different components are working nicely together. We need less of these than unit tests.

E2E tests

Test everything from frontend to backend (End To End), usually these are browser tests. These test ensure that the whole system works as expected from user experience, to backed functionalities. They are slow and expensive. My advice is that you only write them for the most critial parts of the system.

Let's see some CODE already!

Setting up PHPUnit

I assume that your project already uses composer and PSR-4 autoloading. So let' install phpunit:

composer require --dev phpunit/phpunit

We install phpunit with --dev option to make it a dev dependency only. We don't need phpunit in production, and we can skip it in deploy process for example.

Our composer json looks similar to this


{
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    },
    "require-dev": {
        "phpunit/phpunit": "^9.5"
    }
}

Our application classes live in the app directory using the App namespace, and our tests live in the tests directory using Tests namespace.

We create the basic phpunit.xml to instruct phpunit how to run our tests:


<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         bootstrap="vendor/autoload.php"
         colors="true"
>
    <testsuites>
        <testsuite name="Unit">
            <directory suffix=".php">./tests</directory>
        </testsuite>
    </testsuites>
    <php>
        <env name="APP_ENV" value="testing"/>
    </php>
</phpunit>

We created one test suite a named it "Unit", which runs all the .php files from the "tests" directory. If you are interested in more details about phpunit configuration, please check the phpunit documentation.

Create the first tests

When doing test drive development, we do the following steps:

Write a failing test (but only the bare minimum - for the first step)
Write the code which makes the test pass (but only write that much code, which satisfies the test, no more)
Add more assertion to the test, so it fails again
Implement the required feature
Repeat until the feature is complete
Refactor the code, and make sure the tests still pass

Lets create our first test in test/Unit/CartTest.php:


<?php

namespace Unit;

use PHPUnit\Framework\TestCase;
use App\Cart;

class CartTest extends TestCase
{
    public function testAddItemToCart()
    {
        $cart = new Cart();

        $this->assertNotNull($cart);
    }
}

Run the phpunit:

vendor/bin/phpunit

The test will obviously fail, because we don't even have the Cart class, so create the class in app/Cart.php


<?php

namespace App;

class Cart
{

}

Run the phpunit again, and our tests should pass now

vendor/bin/phpunit

Our next step is to implement some functions to the cart. So lets expand our test and make it fail again:


public function testAddItemToCart()
{
    $cart = new Cart();

    $cart->addItem('P111', 'Pizza', 1, 110000);
}

Now lets add the $items property and an addItem method to the Cart:


class Cart
{
    protected array $items = [];

    public function addItem(string $code, string $name, int $quantity, int $price)
    {
        $this->items[] = [
            'code' => $code,
            'name' => $name,
            'quantity' => $quantity,
            'price' => $price
        ];
    }
}

Our test passes again, but we didn't do any proper assertation to makes sure that the method does what it should. So let's do this, assert that the number of the items in the cart equals to 1:


public function testAddItemToCart()
{
    $cart = new Cart();

    $cart->addItem('P111', 'Pizza', 1, 110000);

    $this->assertCount(1, $cart->getItems());
    $this->assertNotNull($cart);
}

If we run this test again, it fails, because we don't have getItems method yet, so let's create it:


/**
 * @return array
 */
public function getItems(): array
{
    return $this->items;
}

Running the test will pass, and this way we developed the first version of the method using TDD.

Now we have the ability to add items to cart, our next step is to implement a method to remove items from the cart. So we create a test for it. As a first step we create the test method without any assertion just call the remove items method:


    public function testRemoveItemFromCart()
    {
        $cart = new Cart();
        $cart->addItem('P111', 'Pizza', 1, 110000);         
        $cart->removeItem('P111');     
    }

We have failing test now because the method doesn't exist yet. Let's create it:


    public function removeItem(string $code)
    {
    }

We created the dummy method, but our test is not erroring out anymore. Now we add the assertion to the test and actually implement the method:


    public function testRemoveItemFromCart()
    {
        $cart = new Cart();
        $cart->addItem('P111', 'Pizza', 1, 110000);

        $cart->removeItem('P111');

        $this->assertCount(0, $cart->getItems());
    }

First we do a very basic implementation of the removeItem method:


    public function removeItem(string $code)
    {
        foreach ($this->items as $index => $item)
        {
            if ($item['code'] === $code){
                unset($this->items[$index]);
            }
        }
    }

This basic implementation, but it works, and the test passes. Now let's refactor it. As we already have test coverage, we can do it confidently, knowing that the functionality remanins the same:


    public function removeItem(string $code)
    {

        $this->items = array_filter($this->items, fn($item) => $item['code'] !== $code);

    }

The next step is to make our cart "smarter", so when we add multiple items with the same code, it increments the quantilty instead of adding a new item to the array, so we create the test first:


    public function testAddSameItemMutlipleTimesIncreasesQuantity()
    {
        $cart = new Cart();

        $cart->addItem('P111', 'Pizza', 1, 110000);
        $cart->addItem('P111', 'Pizza', 1, 110000);

        $expected = [
            [
                'code' => 'P111',
                'name' => 'Pizza',
                'quantity' => 2,
                'price' => 110000
            ]
        ];

        $this->assertEquals($expected, $cart->getItems());
    }

This failes becaue the current cart will add the item twice to the array. So we are changing it:


    public function addItem(string $code, string $name, int $quantity, int $price)
    {
        foreach($this->items as $index => $item) {
            if ($item['code'] === $code){
               $this->items[$index]['quantity'] += $quantity;
               return;
            }
        }

        $this->items[] = [
            'code' => $code,
            'name' => $name,
            'quantity' => $quantity,
            'price' => $price
        ];
    }

We added the foreach to check if we already have that item in the cart, and if yes, we increase the quantity. Otherwise just add the item to the items. Now the all the tests will pass. As we added this new feature to the add items, we need to modify the remove items as well to support this functionality.

We create a test, and add two different items a pizza and two beers :), and assert the removal of one beer decrements the quantity:


    public function testRemoveItemDecreasesQuantityOrRemovesItem()
    {
        $cart = new Cart();
        $cart->addItem('P111', 'Pizza', 1, 110000);
        $cart->addItem('B111', 'Beer', 2, 10000);

        $cart->removeItem('B111');

        $expected = [
            [
                'code' => 'P111',
                'name' => 'Pizza',
                'quantity' => 1,
                'price' => 110000
            ],
            [
                'code' => 'B111',
                'name' => 'Beer',
                'quantity' => 1,
                'price' => 10000
            ]
        ];

        $this->assertEquals($expected, $cart->getItems());
    }

Once we have this failing test we change the removeItem method:


    public function removeItem(string $code)
    {
        foreach($this->items as $index => $item) {
            if ($item['code'] === $code){
                $this->items[$index]['quantity']--;
                return;
            }
        }
    }

Running our new test passes, but oops, we introduced a bug! Running a whole test suite we notice that our previous test for removeItem fails.

Let's fix that:


    public function removeItem(string $code)
    {
        foreach($this->items as $index => $item) {
            if ($item['code'] === $code){
                if ($item['quantity'] > 1){
                    $this->items[$index]['quantity']--;
                }
                else {
                    unset($this->items[$index]);
                }

                return;
            }
        }
    }

Now all out tests should pass, and we have a working cart with add and remove functions. This example proves the point that TDD can prevent itroducing bugs in the existing functionality.

Of course we can add more assertions and more features to it, but it is out of scope for this blog post, my goal was to show the method how the TDD can be part of the process of writing code and even be fun.

Some useful resources

If you'd like to learn more about testing, I can recommend to check out the following links:

The code of the above example, and a Laravel example on GitHub:

We held a meetup on this topic, please find the slides from the meetup below:

https://github.com/daniel-werner/lets-do-tdd-php/blob/main/presentation/Lets%20do%20tdd.pdf

If interested in the meetup, please find the video of the presentation below:

Under the hood: How states work in Laravel factories

Daniel Werner — Sat, 06 Nov 2021 11:46:04 +0000

Since Laravel 8 we can use the new and reworked model factories. They allow us to create multiple interconnected model instances using a simple and easy to read syntax. As usual Laravel has a great documentation about how to create and write these factories. In this article I don’t describe the usage of the factories, if you are interested in that check out the documentation. Instead we will go a little deeper and understand how the states work in factories. Also we will show an interesting example we run into lately, where the states worked differently as we expected.

What are the states?

From the documentation: “State manipulation methods allow you to define discrete modifications that can be applied to your model factories in any combination.” Basically it allows us to define for example a status of the model you create, or basically predefine any of the model attributes.

According to the documentation you should pass a closure to the state method, however you can also pass a simple array, because it will wrap it into a closure:

public function state($state)
{
    return $this->newInstance([
        'states' => $this->states->concat([
            is_callable($state) ? $state : function () use ($state) {
                return $state;
            },
        ]),
    ]);
}

If you define a sequence it basically also add a state on the factory:

public function sequence(...$sequence)
{
    return $this->state(new Sequence(...$sequence));
}

When the factory creates a new model instance it will call the state callback, to apply the changes to the model attributes:

protected function getRawAttributes(?Model $parent)
{
    return $this->states->pipe(function ($states) {
        return $this->for->isEmpty() ? $states : new Collection(array_merge([function () {
            return $this->parentResolvers();
        }], $states->all()));
    })->reduce(function ($carry, $state) use ($parent) {
        if ($state instanceof Closure) {
            $state = $state->bindTo($this);
        }

        return array_merge($carry, **$state($carry, $parent)**);
    }, $this->definition());
}

What has tricked us?

As I mentioned earlier is is also possible to pass a simple array to the state, and it works fine with static values, like:

->state(['status' => 'draft'])

In our case we wanted to create multiple instances of a model, and pass a state which is generated by faker with some special rules like this:

->count(3)->state(['value' => $this->faker->numberBetween(0, 10)])

This is obviously a simplified example in the real case we did multiple instances with the same faker with different conditions. And here comes the trick. It generated all the instances with the same value. Why this has happened? As we saw earlier when you pass a non callable argument to the state it will wrap it into a closure. And basically the faker will be called only once, when you pass the array, and the generated closure for the state will look like this:

function () {
    return ['value' => 4];
}

And this state closure will be executed over and over again so it will return the same value for all models. But when we realised this, and passed a closure our closure looked like this:

function () {
    return ['value' => $this->faker->numberBetween(0, 10)];
}

and in this case the faker is executed for all generated models separately, and generated different random values as expected.

What we could have done differently?

In this case we could use sequences. Those are basically intended for these purposes.

->state(new Sequence(
    fn ($sequence) => ['value' => $this->faker->numberBetween(0, 10)],
))

I wanted to show one interesting thing for the end of this article. As we already saw the sequence instance is passed to the state. The sequence is not wrapped into a closure because it has an __invoke() method and the php built in is_callable($state) method will return true for those invokable classes.

Hope this article helps you understanding the mechanics behind the factory states and to avoid the same mistake we did.

The post Under the hood: How states work in Laravel factories appeared first on Daniel Werner.

Testing with Mocha – 5. BDD style assertions with Chai

Daniel Werner — Thu, 22 Apr 2021 06:56:50 +0000

Chai is a TDD and BDD library, and comes with several flavors for assertions: should, expect and assert. In the following lessons we will take a look at both styles and see how to use them in practice.

Installation and first example

First we need to install chai using a package manager, for example npm:


npm install chai

When it is done, let’s take a look at our first example with chai.

See the Pen Testing with Mocha – Example 5.1 by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

As we see in this example we are using expect instead of assert, let’s see some more details about the different assertion styles, which can be used in Chai.

The BDD style assertions are expect and should. Both use the chainable getters to create nice and readable assertions.

The basic difference between expect and should is how they create the chain of expectations.

Expect

Using expect you have to wrap the asserted value with and expect() function call, and create the chainable assertion afterwards. Let’s see an example.

See the Pen Testing with Mocha – Example 5.1 by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

Should

Should provides the same chainable interface as expect, but should extends all the objects with a should property. This should property can be used to create the assert chain.

Let’s see the previous example rewritten with should.

See the Pen Testing with Mocha – Example 5.2 by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

Important to notice, that as opposed to expect should function should actually be called after requiring it.


const should = require('chai').should()

When using should with ES2015 style imports, the function call should go on separate line, like:


import chai from 'chai';
chai.should();

As opposed to equal, which only needs to be required/imported.


const expect = require('chai').expect;

For more information about should and expect style assertions check the Chai documentation.

Check out all posts in the series Testing with Mocha.

The post Testing with Mocha – 5. BDD style assertions with Chai appeared first on Daniel Werner.

Testing with Mocha – 4. Testing error handling

Daniel Werner — Tue, 20 Apr 2021 06:46:20 +0000

In this post we will take a look how can we expect that an error is thrown and how to make sure no error is thrown when when everything should be fine.

Asserting an error is thrown

Let’s take a look on how to make sure the expected error is thrown in case when we need it. As an example lets extend our generic collection class, and create a specific collection which can store only numeric values.

See the Pen Testing with Mocha – Example 4.1 by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

As we can see in the example above, the numeric collection throws and error when we try to push a non numeric value in it.


    if (typeof item !== 'number') {
        throw new TypeError('Numeric collection can only store numbers!')
    }

In the test we make sure, that this specific error occurs when we try to push a string to our numeric collecion.


     assert.throws(
          () => collection.push("4"),
          TypeError
      );

Asserting an error is not thrown

As we’ve seen in the previous example we can assert that a specific error is thrown when necessary. We can also make sure that the error is not thrown when everything should work fine. The following example shows that the numeric collection accepts an integer value without throwing the type error.

See the Pen Testing with Mocha – Example 4.2 by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

As you can see, this example is almost the same as the previous. The only important difference is that we pushed an integer to the numeric collection,


collection.push(4)

and we asserted that the code does not throw a TypeError:


         assert.doesNotThrow(
              () => collection.push(4),
              TypeError
          );

Check out all posts in the series Testing with Mocha.

The post Testing with Mocha – 4. Testing error handling appeared first on Daniel Werner.

Testing with Mocha – 3. Testing asynchronous code

Daniel Werner — Wed, 14 Apr 2021 06:23:02 +0000

In JavaScript we often write asynchronous code, for example ajax calls, database operations etc. When testing our code we want to be able to test this asynchronous parts of our code as well. Let’s see how we can achieve this when testing with Mocha.

Asynchronous code with callbacks

For testing async code which uses callbacks we can use Mocha’s done function. When passing done in the test Mocha knows that it should wait for that callback to be called. Let’s see and example. Let’s add a save method to our collection, which will operate asynchronously.

See the Pen Testing with Mocha – Example 3.1 by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

Asynchronous code with Promises

If our code use promises instead of callback we can use doesNotReject assertion. Note: when testing promises do not use the done callback. Let’s see and example how to test promises. We’ll “reimplement” the save method of our collection to use promises.

Important: When asserting promises, you should return the result of the assertion for Mocha to pick them up. Otherwise you’d in case when test should not pass, it passes, but you’d get an error.

See the Pen bGgvJYg by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

Asynchronous code with async/await

If our code uses async/await, we can test it easily with Mocha. Let’s rewrite the previous example from using promises to use async/await.

See the Pen QWdmXBb by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

As you can notice, we’ve added the async keyword to the save method, and when calling the method we use the await to wait for the asynchronous call result.


let result = await collection.save();

Check out all posts in the series Testing with Mocha.

The post Testing with Mocha – 3. Testing asynchronous code appeared first on Daniel Werner.

Testing with Mocha – 2. Using the assert library

Daniel Werner — Tue, 13 Apr 2021 15:00:43 +0000

In the previous lesson we’ve created our first test, but used only one assertion to check if the result equals to a predefined value. Let’s take a look at the capabilities of the Chai’s assert library, and explore them through some more advanced examples.

Using strictEqual and notStrictEqual

In the first example we’ve already used the equal assertion. The basic difference between equal and strictEqual is that the latter compares the types as well. The strictEqual only accept the value if it’s type and value is the same as the expected one.

Let’s see and example of how to use the strictEqual. We’ll use the example from the previous lesson and assert that our sum method return the correct result, this time type checking. Also we add a new functionality to the sum method, if it encounters a non numeric item in the data, it returns null. We’ll also create a test for that.

See the Pen Testing with Mocha – Example 2.1 by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

Sometimes we may want to assert that the result of a method call does NOT equal to a given value. In our example the sum method can return a number when the sum is successful or null if it is not. Let’s create an assertion that it never returns false.

See the Pen Testing with Mocha – Example 2.2 by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

Comparing objects

We’ll continue to develop our collection class from the previous lesson, add more features to it and learn the other assertion types.

The assert.deepStrictEqual

The equal assertion cannot be used on object, like our collection. For this purpose we can use the deep strict equal assertion. It checks the objects own enumerable properties, and strictly checks their types.

See the Pen Testing with Mocha – Example 2.3 by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

As we saw in the previous example if the assertion fails when only the type differs in the data. Let’s see another use case for this. We’ll add a push method to our collection. The push method can be used to add new element to the collection.

See the Pen Testing with Mocha – Example 2.4 by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

As we can see from the above example, we use the push method to add a new element to the collection, and use the deepStrictEqual to make push method works correctly, and the collection has the same elements as expected.


let expectedCollection = new Collection([1,2,3,4])

              collection.push(4);
              assert.deepStrictEqual(collection, expectedCollection);

Check out all posts in the series Testing with Mocha.

The post Testing with Mocha – 2. Using the assert library appeared first on Daniel Werner.

Testing with Mocha – 1. Installation and set up

Daniel Werner — Mon, 12 Apr 2021 08:25:36 +0000

Introduction

Mocha can be run both from the command line or from the browser. If you want to run it from the terminal you can use npm or yarn to install it. You can install mocha globally and use it in all your projects or install as as dev dependency in the project locally. I’d recommend installing it locally because this way you can have different versions of Mocha in different projects, and also it makes it easier to install Mocha in continuous integration system to automate the test suite.

Installing Mocha

Installing via command line

Let’s see how to install it globally using npm:

npm install --global mocha

Using this method mocha is installed in the project’s node_modules directory, and it’ll be accessible only in that specific project.

If you use yarn, run:

yarn add mocha

Installing in the browser

For running mocha in the browser you need to load mocha.js and mocha.css in your html. The advantage of using Mocha in browser is that you get a nice test report in the browser, and you don’t have to install via npm. But for me the huge disadvantage is that it cannot be automated. For example cannot be included in the build process. A typical html for running Mocha tests looks like this:


<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Mocha Tests</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="https://unpkg.com/mocha/mocha.css" />
  </head>
  <body>
    <div id="mocha"></div>

    <script src="https://unpkg.com/chai/chai.js"></script>
    <script src="https://unpkg.com/mocha/mocha.js"></script>

    <script class="mocha-init">
      mocha.setup('bdd');
      mocha.checkLeaks();
    </script>
    <script src="test.array.js"></script>
    <script src="test.object.js"></script>
    <script src="test.xhr.js"></script>
    <script class="mocha-exec">
      mocha.run();
    </script>
  </body>
</html>

Creating our first test

How to run mocha

In the previous lesson we installed Mocha, let’s create our first test.

If we installed mocha globally, then we can run it simply by running:


mocha

or if we installed locally, run it like:


./node_modules/mocha/bin/mocha

By default mocha looks for the test files in the test directory, so we can either create a test directory in the project – and run the tests with the above commands -, or we can specify the pattern where to look for the test files, for example:


mocha ./*.js

The above pattern means look at the current directory, and run every .js file in this directory. There are other configuration options as well, we’ll check them out in the following lessons.

Our first test

Let’s create our first test. We’ll start with creating a simple class called Collection to extend the capabilities of the built in JavaScript array. It accepts an array in the constructor and has a sum method to sum all the values of the array. Please find the executable code snippet below.

See the Pen Testing with Mocha – First test by Daniel Werner (@daniel-werner-the-decoder) on CodePen.

Let’s take a look what we have here in this test. In this example we use the node.js’ built in assertion module:


var assert = require('assert');

Using the describe() function we can define the test suite, or we can say organize the tests in logical groups. You can nest the describe() functions according to your needs, to have a nice and structured output, like we did in the example:


describe('Collection', function () {
  describe('#sum()', function () {

The it() function defines the actual test which should do the testing and the assertions:


it('should return 6 ', function () {

We do the assertion with the assert library, in this case asserting that the result equals to the expected value:


assert.equal(collection.sum(), 6);

Thats it! We created our first working test with Mocha! In the following lessons we’ll take a deeper look at how to configure mocha, how to create more complex tests and how to use different assertion libraries with Mocha.

Check out all posts in the series Testing with Mocha.

The post Testing with Mocha – 1. Installation and set up appeared first on Daniel Werner.

Under the hood: How database transactions work in Laravel

Daniel Werner — Mon, 01 Feb 2021 17:00:00 +0000

Continuing the under the hood series, this time about database transactions in Laravel. I won’t repeat all the things on how you can use the transactions in Laravel. If you are not familiar with the topic you can find everything in the documentation here. We’re now focusing on how these implementations work in the background, what caused us some headache lately and how to avoid it. So let’s dive in.

Transactions with closure

As you are probably already familiar with it, you can use closures in the DB facade’s transaction method, like this:

DB::transaction(function () {
    DB::update('update users set votes = 1');
    DB::delete('delete from posts');
});

Using this method you don’t need to worry about starting the transaction, committing and rolling back if anything goes wrong, it does all of that automatically.

The transaction related methods are located in the Illuminate/Database/Concerns/ManagesTransactions.php trait. You can also pass a second argument to the DB::transaction method which is the number of attempts to try the transaction again when an exception or deadlock occur. The code loops through the given number of attempt and starts a new transaction.

public function transaction(Closure $callback, $attempts = 1)
{
    for ($currentAttempt = 1; $currentAttempt <= $attempts; $currentAttempt++) {
        $this->beginTransaction();

It will try to execute the callback function, and if any exception occurs in the callback, rolls back the transaction. It will try again until it reaches the defined number of attempts:

try {
    $callbackResult = $callback($this);
}

// If we catch an exception we'll rollback this transaction and try again if we
// are not out of attempts. If we are out of attempts we will just throw the
// exception back out and let the developer handle an uncaught exceptions.
catch (Throwable $e) {
    $this->handleTransactionException(
        $e, $currentAttempt, $attempts
    );

    continue;
}

If everything went fine commits the transaction,

try {
    if ($this->transactions == 1) {
        $this->getPdo()->commit();

        optional($this->transactionsManager)->commit($this->getName());
    }

    $this->transactions = max(0, $this->transactions - 1);
} catch (Throwable $e) {
    $this->handleCommitTransactionException(
        $e, $currentAttempt, $attempts
    );

    continue;
}

returns the callback result and fires a committed event:

$this->fireConnectionEvent('committed');

return $callbackResult;

Using closures is the simplest and easiest way to use transactions in Laravel.

Manual transaction handling

Laravel allows you to control the transaction yourselves. And that is what caused us problems lately. We’ll come to that point soon, but first let’s see how it works:

Start a transaction with DB::beginTransaction();
If everything went well commit using DB::commit();
Or rollback otherwise with DB::rollBack();

It works just fine, but what if you’d like to use nested transactions. MySQL for example doesn’t support nested transactions, but the InnoDB engine supports savepoints.

Laravel makes use of this feature (if supported). So when we call DB::beginTransaction() it counts the nesting level of transactions. According to this nesting level it either creates a new transaction (first time), or creates a savepoint.

if ($this->transactions == 0) {
    $this->reconnectIfMissingConnection();

    try {
        $this->getPdo()->beginTransaction();
    } catch (Throwable $e) {
        $this->handleBeginTransactionException($e);
    }
} elseif ($this->transactions >= 1 && $this->queryGrammar->supportsSavepoints()) {
    $this->createSavepoint();
}

In situations when the nesting level is more than one, calling the DB::rollBack() will decrement the counter, and roll back to the previous savepoint.

protected function performRollBack($toLevel)
{
    if ($toLevel == 0) {
        $this->getPdo()->rollBack();
    } elseif ($this->queryGrammar->supportsSavepoints()) {
        $this->getPdo()->exec(
            $this->queryGrammar->compileSavepointRollBack('trans'.($toLevel + 1))
        );
    }
}

And here comes the tricky part: the DB::commit() will only really commit to the database when the counter equals to 1. Otherwise it only decrements the counter and fires the committed event.

public function commit()
{
    if ($this->transactions == 1) {
        $this->getPdo()->commit();

        optional($this->transactionsManager)->commit($this->getName());
    }

    $this->transactions = max(0, $this->transactions - 1);

    $this->fireConnectionEvent('committed');
}

Obviously this is fine, but you need make sure that for every started transaction you call either commit or rollback. Especially when doing it in a loop.

An example when things go wrong

So here is an example, what caused headache in our case (it is pseudo code, but the essence is the same):

$products = Products::all()
foreach($products as $product){
    try { 
        DB::beginTransaction();

        if ($product->isExpensiveEnough()) {
            continue;
        }

        $product->price += 100;
        $product->save();
        DB::commit();
    }
    catch(Exception $e){
        DB::rollback();    
    }
}

So basically we want to loop through the products and change some attributes according to some conditions. In this pseudo code we want to raise the price for the products which are not expensive enough :-).

So what is the problem with the above example? In case when we update the product and everything goes well, we begin a transaction, update the model, commit. It even works well when an exception occurs, and we do a rollback.

However when the conditions are not fulfilled, and we continue , in the next iteration a new transaction gets created. The transaction counter will be increased to 2. The following commit would not do an actual commit to the database, just decrement the counter. The next iteration would begin a new transaction increase the counter to 2 etc. Once the number of beginTransaction() and commit()/rollback() method get’s “out of sync” the following iterations won’t update the records.

It is not funny when it is a command that runs for couple of hours, and at the end doesn’t update anything it should.

So the lesson we learned here is simple. Always keep in mind that every opened transaction should be concluded with a commit or rollback. Especially in loops.

The post Under the hood: How database transactions work in Laravel appeared first on Daniel Werner.