Forem: Joël Harkes

Context driven development

Joël Harkes — Fri, 20 Dec 2024 12:25:53 +0000

There are tons of resources out there to make you a better engineer. But I have found few to help software engineers understand the trade-offs in actually choosing what's right for them.

Only after working on multiple projects you might learn the actually trade-offs from experience. As using any of these practices always comes with trade-offs, choosing what's right for your context I call Context(ual) driven development (CDD).

I documented a list below which hopefully helps you make a more balanced decision: ⬇️

(respond below with your suggestions and I will curate them and update this post)

Development

Test-Driven Development (TDD): Overkill for trivial or rapidly prototyped features where requirements are highly volatile.
Domain-Driven Design (DDD): Risk of significant overhead and over engineering especially smaller projects and new/unclear domains.
Event-driven development: more complexity in debugging, tracing execution flow, and ensuring eventual consistency of data across service. (useful for decoupling domains and team in bigger projects)
Object-Oriented Programming (OOP): Can introduce unnecessary complexity for simple, procedural tasks or data-heavy scripts. Can be more complex to test.
Functional Programming (FP): less suitable for problems with inherently mutable state, complex (real world) objects or heavy I/O operations where performance is critical.
Extreme Programming (XP) practices (Pair Programming, etc.): Can be disruptive to individual workflows and require significant team buy-in.

Testing

Unit tests: A lot of overhead for new units of code with unstable interfaces. Refactoring code also means refactoring tests. Avoid when the unit is still unstable an relatively new and not your core business.
Integration tests: Great middle-ground but not scalable, might test some unites of code over and over again and can quickly slowdown your CI pipeline.
End-to-end tests: slow, does not provide quick feedback. should be added to deployment process when development is often breaking your business critical flows.

Process

Code Reviews: Can become a bottleneck if not managed efficiently or if reviewers focus on opinions or style over substance.
Static Code Analysis: Can generate excessive noise (false positives) if not configured carefully for the project's specific needs.

Code quality

Design Patterns (e.g., Singleton, Factory): Can lead to over-engineering if applied without a clear, recurring problem to solve.
Event Sourcing: Adds complexity to data storage and querying; not necessary for applications without complex audit trails or time travel requirements.
Command Query Responsibility Segregation (CQRS): Adds complexity; unnecessary for applications with simple data access patterns.
Bounded Context (DDD): Adds complexity for small or simple domains; Can lead to over-partitioning if not done carefully. Have at-least 1 engineering team per domain.
SOLID Principles: Overly strict adherence can lead to over-engineering and overly complex class hierarchies for simple applications; requires careful judgment to balance design principles with practical needs.
Caching: Adds complexity related to cache invalidation and data consistency; very bug-prone only introduce when absolutely necessary!
Queueing: Adds complexity related to message delivery guarantees, message ordering, and handling failures; introduces latency and requires additional infrastructure.

Architecture/Infrastructure

Microservices: Excessive overhead for small applications; introduces significant inter-service communication complexity.
Serverless Computing (FaaS): Introduces vendor lock-in and can make debugging and local development more challenging; can be less cost-effective for long-running or consistently high-traffic applications.
Micro Frontends: Adds complexity related to inter-application communication, state management, and deployment; can lead to performance issues if not implemented carefully.
Backend for Frontend (BFF): Introduces code duplication and can complicate overall architecture if not carefully managed; adds maintenance overhead with multiple backend services to maintain.

Other

Comprehensive Documentation: Can become outdated quickly if not actively maintained; excessive documentation can obscure important information and become a burden rather than a benefit.

All these paradigms are great! but I hope this helps you decide to sometimes not use them (in parts of your codebase).

⬇️ Please comment below your suggestions! ⬇️

Inspecting Server-to-Server Requests in Laravel with Clockwork: A How-To Guide

Joël Harkes — Thu, 13 Apr 2023 09:27:21 +0000

| It's a default feature since 5.3 => https://github.com/itsgoingd/clockwork/pull/693

When building web applications, server-to-server communication is a common requirement. However, when something goes wrong with these requests, it can be challenging to debug the issue without proper insight into what is happening under the hood. Fortunately, Laravel provides an HTTP client that simplifies server-to-server communication, and Clockwork provides a powerful debugging tool that can help us inspect and debug these requests.

In this post, we'll walk through how to use Clockwork to inspect server-to-server requests in Laravel.

use Illuminate\Support\Facades\Http;

$response = Http::get('https://jsonplaceholder.typicode.com/posts/1');
$body = $response->body();

Setting Up Clockwork

Before we can start inspecting our server-to-server requests, we first need to set up Clockwork in our Laravel application. We can install Clockwork by running the following command in our terminal:

composer require --dev itsgoingd/clockwork

Next, we need to register the Clockwork middleware in our application's middleware stack. We can do this by adding the following line to our app/Http/Kernel.php file:

protected $middleware = [
    \Illuminate\Foundation\Http\Middleware\CheckForMaintenanceMode::class,
    \Illuminate\Foundation\Http\Middleware\ValidatePostSize::class,
    \Illuminate\Foundation\Http\Middleware\TrimStrings::class,
    \Illuminate\Foundation\Http\Middleware\ConvertEmptyStringsToNull::class,
    \Illuminate\Foundation\Http\Middleware\TrustProxies::class,

    // Add the following line to register the Clockwork middleware
    \Clockwork\Support\Laravel\ClockworkMiddleware::class,
];

With the Clockwork middleware registered, we can start using it to inspect our server-to-server requests.

Inspecting Server-to-Server Requests

The provided code snippet demonstrates how we can use Clockwork to log the details of our server-to-server requests. We can add this code to a service provider in our application, such as app/Providers/ServiceProvider.php:

<?php

declare(strict_types=1);

namespace App\Providers;

use Illuminate\Http\Client\Events\RequestSending;
use Illuminate\Http\Client\Events\ResponseReceived;
use Illuminate\Support\Facades\Event;

class ServiceProvider extends \Illuminate\Support\ServiceProvider
{
    public function boot()
    {
        Event::listen(function (RequestSending $event) {
            $headersText = collect($event->request->headers())
                ->map(fn($values, $key) => $key . ": " . (is_array($values) ? implode(", ", $values) : $values))
                ->join("\r\n");
            clock("{$event->request->method()} {$event->request->url()}\r\n{$headersText}\r\n\r\n{$event->request->body()}");
        });
        Event::listen(function (ResponseReceived $event) {
            $headersText = collect($event->response->headers())
                ->map(fn($values, $key) => $key . ": " . (is_array($values) ? implode(", ", $values) : $values))
                ->join("\r\n");
            $body = $event->response->body();
            clock("{$event->response->status()} {$event->request->method()} {$event->request->url()}\r\n{$headersText}\r\n\r\n{$body}");
        });
    }
}

In this code snippet, we're using Laravel's event system to listen for RequestSending and ResponseReceived events. When these events occur, we're using the clock function to log the details of the request or response.

We're formatting the logs in a standard HTTP request/response format that includes the request/response status, method, URL, headers, and body.

Here is an example on how this looks like in your local development: http://localhost/clockwork/app#

Stop using isset() in PHP - Try This Instead!

Joël Harkes — Sun, 26 Feb 2023 20:17:09 +0000

If you're a PHP developer, chances are that you've come across the isset() function. It's a handy little function that checks whether a variable is set and not null. However, there's another function that you should consider using instead: array_key_exists().

So why should you use array_key_exists() instead of isset()? The answer is simple: isset() also returns false even though the variable is set to NULL and won't throw an exception. This can cause unexpected behavior in your code and make it harder to debug.

Let's take a look at an example to illustrate this. Consider the following code:

$data = array(
    'foo' => null,
    'bar' => 'baz'
);

if (isset($data['foo'])) {
    echo 'foo is set';
} else {
    echo 'foo is not set';
}

You might expect this code to output "foo is not set" because $data['foo'] is set to null. However, it actually outputs "foo is set". This is because isset() returns false when a variable is set to null.

Now let's rewrite this code using array_key_exists():

$data = array(
    'foo' => null,
    'bar' => 'baz'
);

if (array_key_exists('foo', $data)) {
    echo 'foo is set';
} else {
    echo 'foo is not set';
}

This code correctly outputs "foo is set". array_key_exists() checks whether the specified key exists in the array, regardless of whether its value is null.

Using array_key_exists() instead of isset() can also make your code more readable. If you're checking whether a key exists in an array, it's clearer to use a function that's specifically designed for that purpose.

In conclusion, array_key_exists() is a more reliable and readable way to check whether a key exists in an array than isset(). Remember that isset() returns false even if a variable is set to null, which can cause unexpected behavior in your code. By using array_key_exists(), you can avoid this issue and make your code more readable at the same time.

Make Laravel do type safe validation

Joël Harkes — Fri, 15 May 2020 14:28:31 +0000

Laravel has a nice validation framework, but a big catch is that it doesn't make sure your result has the right types.

here an example:

$data = ['isOk' => '1'];
$result = $this->validate($data, ['isOk' => 'boolean');

$isOkString = $result['isOk'];
$isOkBoolean = (boo;)  $result['isOk'];
if($isOkString === true){
    // wont fall here.
}
if($isOkBoolean === true){
    // but will go here.
}

wouldn't be wonderful to make sure you have no side affects.

Todo this we must create a nice interface to be able to make Rules allow to transform the result. You must subclass the Laravel Validator and extend the method: validateUsingCustomRule

interface RuleTransformsResult
{
    public function transformResult($attribute, $value);
}


class MyTypeSafeValidator extends \Illuminate\Validation\Validator {
    protected function validateUsingCustomRule($attribute, $value, $rule)
    {
        // below is just copy pasted laravel code of method
        if (!$rule->passes($attribute, $value)) {
            $this->failedRules[$attribute][get_class($rule)] = [];

            $messages = (array) $rule->message();

            foreach ($messages as $message) {
                $this->messages->add($attribute, $this->makeReplacements(
                    $message, $attribute, get_class($rule), []
                ));
            }

        // here is where we do our magic
        } elseif ($rule instanceof RuleTransformsResult) {
            $newValue = $rule->transformResult($attribute, $value, $result);
            if($newValue !== $value) {
                Arr::set($this->data, $attribute, $result);
            }
        }
    }
}

Now we can write our own Boolean validator:

class ValidBoolean implements Rule, RuleTransformsResult
{
    public static $validValuesMap = [
        '0' => false,
        '1' => true,
        'false' => false,
        'true' => true,
        'yes' => true,
        'no' => false,
    ];

    public function passes($attribute, $value)
    {
        if (is_bool($value)) {
            return true;
        }

        return array_key_exists((string) $value, self::$validValuesMap);
    }

    public function message()
    {
        return __('validation.boolean');
    }

    public function transformResult($attribute, $value)
    {
        return (bool) $value;
    }
}

Now we can always have a boolean as result:

$data = ['isOk' => '1'];
$result = $this->validate($data, ['isOk' => [new ValidBoolean()]);

if($result['isOk'] === true){
   // yeah we will make it here.
}

Fake Laravel Eloquent relations on the fly

Joël Harkes — Thu, 14 May 2020 20:05:23 +0000

Sometimes you just want to quickly demo something, you are not bothered by constantly setting up your data and relationships.

Its actually super easy to just fake your relationships on the Fly:

trait FakeEloquentRelationships {
    public bool $fakingRelations = false;

    protected function getRelationshipFromMethod($method)
    {
        if ($this->fakingRelations) {
            $relationShip = $this->$method();
            if ($relationShip instanceof Relation) {
                $model = $relationShip->getModel();
                $class = get_class($model);
                $factory = app(Factory::class);

                $item = $factory->of($class)
                   ->state('full') // i use state 'full' to make sure all properties are set but you can ignore this.
                   ->make();
                $expectSingle = $relationShip instanceof BelongsTo || $relationShip instanceof  HasOne;

                return $expectSingle ? $item : [$item];
            }
        }
        parent::getRelationshipFromMethod($method);
    }
}

Now you can use this trait FakeEloquentRelationships on your model set $model->fakingRelations = true and you are good to go. For example:

class User {
    use FakeEloquentRelationships;

    public function role()
    {
        return $this->belongsTo(Role::class);
    }
}


$user = app(Factory::class)->of(User::class)->make();
$user->fakingRelations = true;
$user->role; // welcome to your completely faked role :)

Hope you liked my post.

PS: we actually use this to generate our Open API (swagger) documentation in combination with league/fractal transformers.