DEV Community: Muhammad Hassan

PHP Attributes and Metaprogramming

Muhammad Hassan — Tue, 20 May 2025 21:05:18 +0000

Introduction

Attributes were introduced in PHP 8 around four years ago. As outlined in the RFC, attributes provide a structured and syntactic way to add metadata to declarations such as classes, properties, functions, methods, parameters, and constants. Previously, developers relied on DocBlocks' annotations for this purpose. The syntax of Attributes is as follows:

 <?php

#[Attribute]
class ExampleAttribute
{
    public function __construct(public string $message) {}
}

#[ExampleAttribute('This is a custom attribute for a class')]
class MyClass
{
    #[ExampleAttribute('This is a custom attribute for a method')]
    public function myMethod() { echo "Hello from myMethod!"; }
}

But first, how are PHP attributes different from decorators in Python? Or, Java’s Aspect-oriented Programming (AOP) annotations?

Metaprogramming

The concept that is fundamentally common across Aspect-Oriented Programming (AOP), attributes, and decorators is metaprogramming. Metaprogramming is the practice of writing code that generates, manipulates, or modifies other code. Essentially, it's code that writes code. This can be done at compile-time or runtime, depending on the language and use case.

Decorator

Decorator is a behavioral design pattern where a function or class is wrapped with additional behavior without modifying its structure. Achieved using higher-order functions (in Python, JavaScript) or annotations (in TypeScript).

💡 This is different from the stackable decorator classes implementation of the decorator pattern.

The following is a simple example of a logging decorator in Python.

def log_function_call(func):
    def wrapper(*args, **kwargs):
        print(f"Calling function: {func.__name__}")
        result = func(*args, **kwargs)
        print(f"Function {func.__name__} returned {result}")
        return result
    return wrapper

@log_function_call
def add(a, b):
    return a + b

# Usage
add(3, 4)

log_function_call is a decorator function.
@log_function_call applies that decorator to the add function.
wrapper is a nested function that wraps the original function, adding extra behavior before and after it runs.

The output of this code will be:

Calling function: add
Function add returned 7

Aspect-Oriented Programming

Aspect-Oriented Programming (AOP) is a paradigm that allows you to modularize concerns (like logging, security, or transaction management) that cut across the typical divisions of responsibility (such as methods or classes) by encapsulating them into reusable modules called aspects, improving separation of concerns and making the codebase easier to maintain and extend.

Let’s take another logging example but this time implemented in AOP to explain its core concept:

package com.example.demo.aspect;

import org.aspectj.lang.JoinPoint;
import org.aspectj.lang.annotation.*;
import org.springframework.stereotype.Component;

@Aspect
@Component
public class LoggingAspect {

    @Before("execution(* com.example.demo.service.*.*(..))")
    public void logBefore(JoinPoint joinPoint) {
        System.out.println("[LOG] Method called: " + joinPoint.getSignature().toShortString());
    }
}

The code defines a cross-cutting concern — specifically, logging — and separates it from the main business logic of the application (like the service classes).

Instead of adding System.out.println statements inside every service method, you modularized this behavior into a separate aspect: LoggingAspect.

Element	Explanation
`@Aspect`	Declares this class as an aspect (a modular unit of a cross-cutting concern).
`@Component`	Tells Spring to manage this class as a bean.
`@Before(...)`	A pointcut and advice: it says "Before any method in `com.example.demo.service.*` package is called, run `logBefore()`."
`JoinPoint`	Gives details about the method being intercepted (like its name).
`logBefore()`	This is the advice method where the logging action happens.

In essence, metaprogramming is the conceptual thread that ties AOP, attributes, and decorators together—they’re all ways to step outside the normal flow of code execution and define how code should behave beyond its immediate implementation.

Reflection API

Both the new first-class citizen attributes and the dockblocks implementation depend on the reflection API for inspecting the attributes at runtime. Reflection AP is another, much older, example of metaprogramming in PHP. It introduced the ability to introspect classes, interfaces, functions, methods and extensions. It can also retrieve the doc comments for functions, classes and methods.

If you are not familiar with it, here is a simple example where the properties of the User class can be accessed programmatically regardless of their access modifier:

<?php

class User {
    public function __construct(
        public string $name,
        private int $age,
        protected string $email
    ) {}
}

// Use ReflectionClass to inspect the User class
$reflection = new ReflectionClass('User');

// Get the public, protected, and private properties 
$properties = $reflection->getProperties();

Attributes

Syntax

Attributes are classes annotated with the base #[Attribute]:

#[Attribute(Attribute::TARGET_METHOD)]
class Log
{
    public function __construct(public string $message = 'Method called') {}
}

Attributes are configured by passing a bitmask as its first argument, It can be used to restrict the types that an attribute can be applied to. In the above example, the Log attribute can only be applied to methods. The available types are:

TARGET_CLASS
TARGET_FUNCTION
TARGET_METHOD
TARGET_PROPERTY
TARGET_CLASS_CONSTANT
TARGET_PARAMETER
TARGET_ALL

By default, an attribute can be used once per declaration. to change this behavior, specify it in the bitmask of the #[Attribute] declaration using the Attribute::IS_REPEATABLE flag:

#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
class Log
{
    public function __construct(public string $message = 'Method called') {}
}

Usage

Create a class that uses the Log attribute:

class AccountService
{
    #[Log("Creating a new account")]
    public function createAccount(string $user)
    {
        echo "Account created for $user" . PHP_EOL;
    }

    #[Log("Deleting an account")]
    public function deleteAccount(string $user)
    {
        echo "Account deleted for $user" . PHP_EOL;
    }

    public function helperFunction()
    {
        echo "This won't be logged." . PHP_EOL;
    }
}

Create a logger proxy function to call the methods with logging:

function callWithLogging(object $object, string $method, array $args = [])
{
    $refMethod = new ReflectionMethod($object, $method);
    $attributes = $refMethod->getAttributes(Log::class);

    if (!empty($attributes)) {
        /** @var Log $log */
        $log = $attributes[0]->newInstance();
        echo "[LOG] {$log->message}" . PHP_EOL;
    }

    return $refMethod->invokeArgs($object, $args);
}

Client Code

$service = new AccountService();

callWithLogging($service, 'createAccount', ['alice']);
callWithLogging($service, 'deleteAccount', ['bob']);
callWithLogging($service, 'helperFunction'); // No log, no attribute

The output of this code will be:

[LOG] Creating a new account
Account created for alice
[LOG] Deleting an account
Account deleted for bob
This won't be logged.

Real-Life Example

Let’s take a real-life example of attributes. Laravel 11 introduced contextual attributes and for our example we will be using the Config attribute. The #[Config(...)] attribute allows you to annotate a constructor or method parameter, so that Laravel’s service container can resolve and inject the corresponding config value at runtime:

<?php

namespace App\Http\Controllers;

use Illuminate\Container\Attributes\Config;

class PhotoController extends Controller
{
    public function __construct(#[Config('app.timezone')] protected string $timezone)
    {
        // ...
    }
}

Config Attribute Definition

The Config attribute definition goes as follows:

<?php

namespace Illuminate\Container\Attributes;

use Attribute;
use Illuminate\Contracts\Container\Container;
use Illuminate\Contracts\Container\ContextualAttribute;

#[Attribute(Attribute::TARGET_PARAMETER)]
class Config implements ContextualAttribute
{
    /**
     * Create a new class instance.
     */
    public function __construct(public string $key, public mixed $default = null) {}

    /**
     * Resolve the configuration value.
     *
     * @param  self  $attribute
     * @param  \Illuminate\Contracts\Container\Container  $container
     * @return mixed
     */
    public static function resolve(self $attribute, Container $container)
    {
        return $container->make('config')->get($attribute->key, $attribute->default);
    }
}

ℹ️ The ContextualAttribute is an empty interface in Laravel 12.x.

Resolving `Config` Attribute

Contextual attributes resolving start in Illuminate\Container\Container::build($concrete).

⚠ Some of the code in Illuminate\Container\Container will be omitted if it’s not related to the flow of binding a constructor’s config parameter. The full class can be found here.

First, we create a ReflectionClass to inspect the $concrete class:

try {
    $reflector = new ReflectionClass($concrete);
} catch (ReflectionException $e) {
    throw new BindingResolutionException("Target class [$concrete] does not exist.", 0, $e);
}

The next step is to get the $concrete constructor method:

// returns a ReflectionMethod instance
$constructor = $reflector->getConstructor();

Then, if the class does not have a constructor, the service container returns a new instance of $concrete. But, that is not the case in our PhotoController, so that, it gets a list of the $constructor method parameters:

// returns an array of ReflectionParameter[]
$dependencies = $constructor->getParameters();

try {
    $instances = $this->resolveDependencies($dependencies);
} catch (BindingResolutionException $e) {
    array_pop($this->buildStack);

    throw $e;
}

The method Container::resolveDependencies($dependencies) loops over the $dependencies array, and returns an array of the constructor parameters. One execution flow is when the $dependency has a contextual parameter:

foreach ($dependencies as $dependency) {
    $result = null;

    if (! is_null($attribute = Util::getContextualAttributeFromDependency($dependency))) {
        $result = $this->resolveFromAttribute($attribute);
    }
}

Finally, in Container::resolveFromAttribute(ReflectionAttribute $attribute), There are two scenarios for resolving the value of the attribute:

public function resolveFromAttribute(ReflectionAttribute $attribute)
{
    $handler = $this->contextualAttributes[$attribute->getName()] ?? null;

    $instance = $attribute->newInstance();

    if (is_null($handler) && method_exists($instance, 'resolve')) {
        $handler = $instance->resolve(...);
    }

    if (is_null($handler)) {
        throw new BindingResolutionException("Contextual binding attribute [{$attribute->getName()}] has no registered handler.");
    }

    return $handler($instance, $this);
}

If there is a custom handler function (or callable) for the $attribute name defined in the App\Providers\AppServiceProvider::boot():

use Illuminate\Container\Attributes\Config;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    $this->app->contextualAttributes[Config::class] = fn() => 'Africa/Cairo';
}

The callable fn() => 'Africa/Cairo' is invoked.

If the $handler is null, and the Illuminate\Container\Attributes\Config::resolve() method exists in the attribute definition, it will be invoked.

Attributes Misuse

Metaprogramming allows code to generate or modify other code dynamically, offering flexibility and reduced boilerplate, but it comes with significant downsides. It can reduce readability and maintainability, make debugging harder, and introduce performance overhead.

To minimize the negative side effects of attributes, they should not be used beyond their described purpose as metadata providers. Misuse examples includes:

Embedding logic or side effects within attributes
- For example, having an attribute that modifies global state or performs operations at runtime just by being present.
Replacing business logic with attribute logic
- E.g., putting application logic or decisions into attribute classes, rather than keeping that logic in controllers or services.
Overloading attribute meaning
- When attributes are overloaded with too many responsibilities or become a place to "hide" logic, it becomes harder to understand or maintain code.
Using attributes for code that should remain in configuration files
- E.g., trying to implement environment configuration through attributes.

In conclusion, PHP attributes provide a powerful and expressive way to add metadata to your code, making it easier to build more declarative and maintainable applications. From core language features like #[Deprecated], #[Override], and #[Attribute], to PHPUnit-specific attributes such as #[Test], #[Before], #[After], and #[Depends], attributes help streamline testing and application behavior without relying on verbose annotations or docblocks. As attributes continue to evolve in PHP, they open up cleaner integration points for frameworks and tooling. Whether you're writing application logic or unit tests, leveraging built-in and custom attributes can greatly improve the readability and structure of your codebase.

PHP Generics in Laravel 11

Muhammad Hassan — Tue, 22 Oct 2024 23:11:31 +0000

If you are a web applications builder with Laravel and happens to use PHPStan for static code analysis, you will start seeing new errors when you upgrade to Laravel 11.x.

In a fresh Laravel install with PHPStan, the first time running ./vendor/bin/phpstan the following error get thrown:

 ------ -----------------------------------------------------------------------------------
  Line   app\Models\User.php
 ------ -----------------------------------------------------------------------------------
  13     Class App\Models\User uses generic trait
         Illuminate\Database\Eloquent\Factories\HasFactory but does not specify its types:
         TFactory
 ------ -----------------------------------------------------------------------------------

So what was changed? In Laravel 11, the HasFactory trait now has a PHPDoc with the @template tag which is one of the reserved generics tags. As you may already have guessed, generics are being used in many parts of the framework.

/**
 * @template TFactory of \Illuminate\Database\Eloquent\Factories\Factory
 */
trait HasFactory
{
    ...
}

Although it is not recommended, this category of errors can be ignored by simply adding these lines of code to your phpstan.neon file:

parameters:
    ignoreErrors:
        -
            identifier: missingType.generics

But, generics are not that hard to understand so let’s get started!

What are Generics?

Generics in programming refer to a feature that allows you to write code that can work with multiple data types. Instead of writing separate code for each data type, you can write a single, generic piece of code that can operate on various types while maintaining type safety, unlike using general types like mixed or object.

Take the Illuminate\Database\Concerns\BuildsQueries::first method from Laravel 10, it can return an instance of Model, a general object, an instance of the class using it like Illuminate\Database\Eloquent\Builder or null.

/**
 * Execute the query and get the first result.
 *
 * @param  array|string  $columns
 * @return \Illuminate\Database\Eloquent\Model|object|static|null
 */
public function first($columns = ['*'])
{
    return $this->take(1)->get($columns)->first();
}

Generics Syntax

Generics are not supported in PHP as a first-class citizen, to have them we use the PHPDocs tags @template, @template-covariant, @template-contravariant, @extends, @implements, and @use.

The rules of the generic types are defined using type parameters. In PHPDocs we annotate them with the @template tag. The type parameter name can be anything, as long as you don’t use an existing class name. You can also limit which types can be used in place of the type parameter with an upper bound using the of keyword. This is called bounded type parameter.

<?php

namespace Illuminate\Database\Eloquent;

/**
 * @template TModel of \Illuminate\Database\Eloquent\Model
 *
 */
class Builder implements BuilderContract
{
}

Types of PHP Generics

Generic Function

A generic function is exactly like a normal function, however, it has type parameters. This allows the generic method to be used in a more general way.

Take the Illuminate\Support\ValidatedInput::enum method as an example:

It defines a type parameter TEnum.
The $enumClass parameter is of the pseudo type class-string and bounded to the same type parameter TEnum.
The return type also can either be of TEnum or null.

/**
 * @template TEnum
 *
 * @param string $key
 * @param class-string<TEnum> $enumClass
 * @return TEnum|null
 */
public function enum($key, $enumClass)
{
    if ($this->isNotFilled($key) ||
        ! enum_exists($enumClass) ||
        ! method_exists($enumClass, 'tryFrom')) {
        return null;
    }
    return $enumClass::tryFrom($this->input($key));
}

If you then call $request→validated()→enum(‘status‘, OrderStatus::class), PHPStan will know that you’re getting an OrderStatus object or null!

Generic Class

Generic classes allows for creating classes that can operate on any data type while ensuring type safety. They enable a class to be defined with a placeholder for a specific type, which can later be substituted when the class is instantiated.

A good example from Laravel source code would be the Illuminate\Database\Eloquent\Builder class:

<?php

namespace Illuminate\Database\Eloquent;
/**
 * @template TModel of \Illuminate\Database\Eloquent\Model
 */
class Builder implements BuilderContract
{
    /**
     * @param  array  $attributes
     * @return TModel
     */
    public function make(array $attributes = [])
    {
        return $this->newModelInstance($attributes);
    }
}

A type parameter TModel is defined and bounded to any sub-class of Illuminate\Database\Eloquent\Model. The same type parameter is used as a return type of the method make.

Another example would be if we have an Order model, which has a local scope to filter orders based on their status. The scope method should specify the TModel type

/**
 * @param  Builder<Order>  $query
 */
public function scopeWithStatus(Builder $query, OrderStatus $status): void
{
    $query->whereStatus($status->value);
}

ℹ️ info: All the Eloquent relations classes in namespace Illuminate\Database\Eloquent\Relations like BelongsTo and HasOne are now generic.

Generic Interface

Generic interfaces are not so different. The Illuminate\Contracts\Support\Arrayable is an example of a generic interface

/**
 * @template TKey of array-key
 * @template TValue
 */
interface Arrayable
{
    /**
     * Get the instance as an array.
     *
     * @return array<TKey, TValue>
     */
    public function toArray();
}

The interface defines two type parameters: TKey of type array-key (it can be int or string) and TValue. Theses two parameters are used to define the return type of the toArray function. Here is an example:

/**
 * @implements Arrayable<int, string>
 */
class User implements Arrayable
{
    public int $id;
    public string $name;

    /**
     * @return array<int, string>
     */
    public function toArray(): array
    {
        return [
            $this->id => $this->name,
        ];
    }
}

The user class implements the Arrayable interface and specify the Tkey type as an int and the TValue as a string.

Generic Trait

We came across the Illuminate\Database\Eloquent\Factories\HasFactory trait in the error at the beginning of this post. Let’s have a closer look:

<?php

namespace Illuminate\Database\Eloquent\Factories;

/**
 * @template TFactory of \Illuminate\Database\Eloquent\Factories\Factory
 */
trait HasFactory
{
    /**
     * Create a new factory instance for the model.
     *
     * @return TFactory|null
     */
    protected static function newFactory()
    {
        if (isset(static::$factory)) {
            return static::$factory::new();
        }

        return null;
    }
}

HasFactory defines a type parameter TFactory bounded to the sub-classes of Illuminate\Database\Eloquent\Factories\Factory. So how can that error be fixed?

The TFactory type must be specified when the trait is being used. So, the use statement of the HasFactory trait needs to be annotated with the PHPDocs @use:

<?php

namespace App\Models;

use Database\Factories\UserFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    /** @use HasFactory<UserFactory> */
    use HasFactory;
}

Preserving Genericness

When extending a class, implementing an interface, or using a trait it is possible to maintain the genericness in the sub-class.

Preserving the genericness is implemented by defining the same type parameters above the child class and passing it to @extends, @implements and @use tags.

We will use the Illuminate\Database\Concerns\BuildsQueries generic trait as an example,

it defines a type parameter TValue:

/**
 * @template TValue
 *
 */
trait BuildsQueries
{
    ...
}

The Illuminate\Database\Eloquent\Builder class uses this trait but keeps its genericness by passing the TModel parameter type to it. It is now left to the client code to specify the type of TModel and consequently TValue in the BuildsQueries trait.

/**
 * @template TModel of \Illuminate\Database\Eloquent\Model
 */
class Builder implements BuilderContract
{
    /** @use \Illuminate\Database\Concerns\BuildsQueries<TModel> */
    use BuildsQueries, ForwardsCalls, QueriesRelationships {
        BuildsQueries::sole as baseSole;
    }
}

Final Thoughts

In conclusion, while PHP does not natively support generics in the same way as some other programming languages, the introduction of advanced type hints and tools like PHPStan allows developers to implement generics-like functionality in their code. By leveraging PHPDocs, parameterized classes, and interfaces, you can create more flexible and type-safe applications that promote code reusability and maintainability. As PHP continues to evolve, the community's growing focus on type safety and static analysis will likely lead to more robust solutions for implementing generics. Embracing these practices not only enhances your coding skills but also contributes to the development of high-quality software that stands the test of time.

Creating Refresh Tokens with Laravel Sanctum

Muhammad Hassan — Sat, 03 Jun 2023 12:19:04 +0000

Laravel Sanctum is a lightweight authentication package for SPA applications and APIs. It was released in 2020 and became available out of the box since Laravel 8. Unlike JWT self-contained tokens, Sanctum uses a reference token.

What is a Reference Token?

A reference token is a type of authentication token that contains a reference to the actual data stored on the server side in some data storage. This reference can be used to look up the actual data and verify the authenticity of the token.
Sanctum uses the database as its storage, and if we take a look at the Sanctum personal_access_tokens database table, we notice that it contains information about the eloquent model that is being authenticated, the token abilities when it was last used and its expiration timestamp.

public function up(): void
{
    Schema::create('personal_access_tokens', function (Blueprint $table) {
        $table->id();
        $table->morphs('tokenable');
        $table->string('name');
        $table->string('token', 64)->unique();
        $table->text('abilities')->nullable();
        $table->timestamp('last_used_at')->nullable();
        $table->timestamp('expires_at')->nullable();
        $table->timestamps();
    });
}

Advantages of Reference Tokens

Reference tokens can be preferred in scenarios where the token payload is too large to be included directly in the token.
Since reference tokens do not include all the necessary data, the risk of data breaches is reduced.
The token data can be updated or changed without having to invalidate the old token and issue a new one to the client. This can also lead to better scalability since the number of issued and managed tokens is reduced.
Being smaller in size compared to self-contained tokens, they can be transmitted and processed faster.

Why Refresh Tokens Are Needed?

The purpose of Refresh Tokens is to obtain long-term access to an API on behalf of the user which provides a better user experience as users do not need to re-enter their credentials every time their access token expires.

So, why do not we issue access tokens with a long time-to-live (TTL)? While extending the TTL of an access token may seem like a simple solution, it can increase the risk of security breaches. The longer an access token is valid, the longer a compromised token can be used to access the user's data until it expires.

Issuing Refresh Tokens with Sanctum

1. Configure Time-to-Live Values

There is a difference in the time-to-live between access tokens and refresh tokens but Sanctum has only one configuration for expiration in config/sanctum.php. Let's start by adding another configuration for refresh tokens expiration named rt_expiration

<?php

return [
    .
    .
    .
    'expiration' => 60,              // One hour
    'rt_expiration' => 7 * 24 * 60,  // 7 Days
];

2. Overriding Sanctum Service Provider

Although the new rt_expiration configuration to create the refresh tokens, Sanctum will always use the expiration value to check on the token validity. In Laravel\Sanctum\SanctumServiceProvider, the request guard is created using the default expiration:

/**
 * Register the guard.
 *
 * @param  \Illuminate\Contracts\Auth\Factory  $auth
 * @param  array  $config
 * @return RequestGuard
 */
protected function createGuard($auth, $config)
{
    return new RequestGuard(
        new Guard($auth, config('sanctum.expiration'), $config['provider']),
        request(),
        $auth->createUserProvider($config['provider'] ?? null)
    );
}

The TTL value should be selected based on the incoming request. First, let’s define a new configuration for the refresh token URL pattern:

<?php

return [
    'rt_url_pattern' => env('SANCTUM_RT_URL_PATTERN', '*/auth/refresh-token'),
];

Then, create a new service provider:

php artisan make:provider SanctumServiceProvider

This provider will extend the package’s provider and it will have the new implementation of the createGuard method:

<?php

namespace App\Providers;

use Illuminate\Auth\RequestGuard;
use Illuminate\Contracts\Auth\Factory;
use Laravel\Sanctum\Guard;

class SanctumServiceProvider extends \Laravel\Sanctum\SanctumServiceProvider
{
    /**
     * Register the guard.
     *
     * @param  Factory  $auth
     * @param  array<string, mixed>  $config
     */
    #[\Override]
    protected function createGuard($auth, $config): RequestGuard
    {
        $expiration = request()->is(config('sanctum.rt_url_pattern'))
            ? config('sanctum.rt_expiration')
            : config('sanctum.expiration');

        return new RequestGuard(
            new Guard($auth, $expiration, $config['provider']),
            request(),
            $auth->createUserProvider($config['provider'] ?? null)
        );
    }
}

The final step is to tell Laravel not to load the package’s service provider. In composer.json, update the the extra property as follows:

"scripts": {
   "extra": {
        "laravel": {
            "dont-discover": [
              "laravel/sanctum"
            ]
        }
    }
}

3. Define Token Abilities

The refresh token should have one ability, which is issuing new access tokens. One way to do this is by creating an enumeration for token abilities at app\Enums\TokenAbility.php

<?php

namespace App\Enums;

enum TokenAbility: string
{
    case ISSUE_ACCESS_TOKEN = 'issue-access-token';
    case ACCESS_API = 'access-api';
}

Now, when a user login two tokens will be issued

use Illuminate\Http\Request;
namespace App\Enums\TokenAbility;

Route::post('/auth/login', function (Request $request) {
    // Credentials check should go here.

    $accessToken = $user->createToken('access_token', [TokenAbility::ACCESS_API->value], config('sanctum.expiration'));
    $refreshToken = $user->createToken('refresh_token', [TokenAbility::ISSUE_ACCESS_TOKEN->value], config('sanctum.rt_expiration'))

    return [
        'token' => $accessToken->plainTextToken,
        'refresh_token' => $refreshToken->plainTextToken,
    ];
});

To use the token abilities in protecting routes, we need to add Sanctum abilities middlewares. In Laravel 10.X and prior, the middlewares should be added to the $middlewareAliases property in app/Http/Kernel.php file:

'abilities' => \Laravel\Sanctum\Http\Middleware\CheckAbilities::class,
'ability' => \Laravel\Sanctum\Http\Middleware\CheckForAnyAbility::class,

Starting from Laravel 11.X, middlewares configuration is part of the application bootstrap file at ./bootstrap/app.php:

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->alias([
            'abilities' => \Laravel\Sanctum\Http\Middleware\CheckAbilities::class,
            'ability' => \Laravel\Sanctum\Http\Middleware\CheckForAnyAbility::class,
        ]);
    })
    ->create();

4. Assign the Ability Middleware to Routes

Finally, the route for issuing a new access token should be protected by the ability middleware

use Illuminate\Http\Request;
namespace App\Enums\TokenAbility;

Route::post('/auth/refresh-token', function (Request $request) {
    $accessToken = $request->user()->createToken('access_token', [TokenAbility::ACCESS_API->value], config('sanctum.expiration'));

    return ['token' => $accessToken->plainTextToken];
})->middleware([
    'auth:sanctum',
    'ability:'.TokenAbility::ISSUE_ACCESS_TOKEN->value,
]);

In summary, refresh tokens can make your application more secure but because they are powerful authentication artifacts, they should be kept secure. You can learn more about securing refresh tokens from this article.

Using ULID in Laravel Framework

Muhammad Hassan — Sat, 20 May 2023 16:10:06 +0000

In a previous post, we talked about how ULID can be a better choice for primary keys in MySQL than UUIDs. In this tutorial, we will go over how to use ULID in Laravel Framework.

ULID has been supported in Laravel since v9.30.1 and has received some improvements in later releases So no third-party packages are needed to use it.

Eloquent Models

Let's take an Article model as an example. First, we create the article's model and migration file as we normally do

php artisan make:model Article

In the up method inside the migration file, the table's primary key will be defined using the ulid method followed by the primary method.

public function up(): void
{
    Schema::create('articles', function (Blueprint $table) {
        $table->ulid('id')->primary();
        $table->string('title');
        $table->text('body');
        $table->timestamps();
    });
}

What the [ulid](https://github.com/laravel/framework/blob/9.x/src/Illuminate/Database/Schema/Blueprint.php#L1288) method does is create a column of type CHAR and set its length to 26 bytes instead of the 36 bytes needed for UUIDs.

Then in the Article eloquent model, the Illuminate\Database\Eloquent\Concerns\HasUlids trait will be added

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    use HasFactory, HasUlids;
}

Laravel also has a method in the Illuminate\Database\Schema\Blueprint class for creating foreign keys that references a table with ULID primary key.

In our example, we can add a Comment model and each comment belongs to one Article. The foreign key of the articles table is defined using the foreignUlid method

public function up(): void
{
    Schema::create('comments', function (Blueprint $table) {
        $table->uuid('id')->primary();
        $table->string('body');
        $table->foreignUlid('article_id')->constrained();
        $table->timestamps();
    });
}

And the last method is ulidMorphs that create the columns needed for a polymorphic relation. Let's add another Tag model that can be linked to many models not just Article. The taggables table can be defined like this:

public function up(): void
{
    Schema::create('taggables', function (Blueprint $table) {
        $table->foreignUlid('tag_id')->constrained();
        $table->ulidMorphs('taggable');
    });
}

Str Facade

ULID can be created anywhere in your app using the ulid method in the Illuminate\Support\Str facade.

Str::ulid()->toBase32()

The above statement returns the ULID and it will look something like this 01H0WXWP3XGAX0ZJVG7Q2E70FC.

Finally, if you are interested in the implementation being used to generate ULID, check out the Symfony UID component that Laravel uses.

Using Unique Identifiers as Primary Key in MySQL

Muhammad Hassan — Sun, 30 Apr 2023 21:06:02 +0000

Using Unique Identifiers as Primary Key in MySQL

Unique identifiers are used to distinguish one object from another. They are commonly used to identify entities such as users, files, processes, network devices, and other objects. Unique identifiers are often implemented using a numerical or alphanumeric string that is assigned to an object when it is created and they have many types like UUID, ULID, Snowflake ID, GUID and more.

Using integers for tables’ primary key is the go-to approach when working with MySQL and other RDBMS. But, using unique identifiers instead of auto-incremented integers can have some benefits like:

Unique identifiers have a low probability of collision even across tables and databases.
They can be generated by the application without a centralized authority.
And since they are pseudo-random, they can be sent safely to the client side.

But as with any tech or tool there are some tradeoffs that come with using unique identifier.

UUIDs

UUID stands for Universally Unique Identifier, which is a standard for generating unique identifiers that are widely used in computer systems and software applications. UUID consists of two parts: a time-based component and a random component, and there are officially 5 versions of UUID, each with different algorithm for generating the random and time-based components. The 128-bit value of a UUID is usually represented as a string of 36 characters, consisting of 32 hexadecimal digits separated by hyphens in the form of 8-4-4-4-12. For example, a UUID might look like this: 245dffb2-7068-405f-b759-88c3ef8bcf3d.

UUIDs are Pseudo Random

The negative impact of using UUID as primary key comes from how MySQL’s default engine, InnoDB, stores the data. InnoDB by default creates a b-tree for the table’s primary key and stores the rows data in the leaf nodes of the same b-tree which is called a clustered index. In other words, when a table has a clustered index, the data is physically stored on the disk in the same order as the index.

When a new row with a random UUID needs to be inserted, InnoDB needs to:

Checks whether the page is already in the buffer pool
If the page is not in the buffer pool, InnoDB reads the page from disk.
Write the page to the buffer pool.
Insert the new row.
At some point, the page will be flushed back to the disk.

Normally when a page is frequently accessed and modified it becomes a hot page, and the buffer pool gives it higher priority to stay in memory as long as possible. This can result in performance gains in terms of latency and throughput. But, when the primary key is random, it is unlikely for a page to become frequently accessed thus each insert will mostly require an extra disk I/O.

Additionally, inserting rows with random primary key can cause more page splits. A page split occurs when an InnoDB page becomes full and cannot accommodate the new data. thus it needs to be divided into two or more smaller pages. This operation is costly in terms of performance as it requires many disk I/O operations to read and write data.

Random primary keys can also lead to page low filling factor. According to MySQL documentation:

When new records are inserted into an InnoDB clustered index, InnoDB tries to leave 1/16 of the page free for future insertions and updates of the index records. If index records are inserted in a sequential order (ascending or descending), the resulting index pages are about 15/16 full. If records are inserted in a random order, the pages are from 1/2 to 15/16 full.

UUIDs Size

UUIDs have a size of 128 bits and their hexadecimal form (8-4-4-4-12) can be stored in a CHAR(36) column because each hexadecimal digit represents 4 bits so it will 32. However, since each character in a CHAR column in MySQL is represented by one byte of storage, 36 characters (32 for the digits and 4 for the hyphens) in a CHAR(36) column will require 36 bytes of storage.

Having 36 bytes for the primary key does not seem to be a lot at first glance and to put it into perspective lets assume a table with a UUID primary key and 4 secondary indexes. Considering that each secondary index store the primary key of its row, the UUID will be stored 5 times for each row. If the table has 1 million rows the storage required will be

6 x 36 = 216 bytes of storage per row
For the 10M rows: 10,000,000 rows x 216 bytes/row = 2,160,000,000 bytes
To convert this to gigabytes, we divide by 100,000,000 (the number of bytes in a gigabyte): 2,160,000,000 bytes / 1,000,000,000 bytes/GB = 2.16 GB

ULIDs

ULID stands for Universally Unique Lexicographically Sortable Identifier and it tries to solve some of UUIDs limitations. ULIDs are 26 characters long and consist of two parts:

A 10-character timestamp, measured in milliseconds since Unix epoch time (January 1, 1970, 00:00:00 UTC). This provides the chronological ordering of ULIDs.
A 16-character random value, encoded using a Crockford's base32 encoding. This value ensures that each ULID is unique even if generated at the same time.

Additionally, according to the ULID spec, it can be superior to UUIDs given that:

Has 1.21 X 10^24 possible values per millisecond.
Lexicographically sortable
Canonically encoded as a 26-character string, as opposed to the 36-character UUID
Case insensitive
URL safe

In conclusion, ULID can solve the performance issues resulting from the randomness of UUID and it is more efficient in terms of storage. So it would be a better alternative to integer primary key than UUIDs. It is also implemented in many programming language

Sending Laravel Logs to Mattermost Channels

Muhammad Hassan — Sat, 24 Sep 2022 09:44:53 +0000

Mattermost is an open-source platform for communication and collaboration with integrations with many tools. It is mostly considered as an open-source alternative to Slack and Microsoft Teams.

Although Laravel does not have an official log channel driver for Mattermost, we can build a custom Monolog handler that can be easily configured in Laravel apps.

I have created a small package for this purpose that, unlike the existing Mattermost handlers, format the message according to Mattermost docs

Installation

$ composer require muhamadhhassan/laramost

Configuration

In your config/logging.php file, add the mattermost channel to the channels array:

use LaraMost\Formatter\MattermostFormatter;
use LaraMost\Handler\MattermostWebhookHandler;

'channels' => [
    'mattermost' => [
        'driver'  => 'monolog',
        'handler' => MattermostWebhookHandler::class,
        'formatter' => MattermostFormatter::class,
        'with' => [
            'hook' => 'https://your-mattermost.com/hooks/random-string',
        ],
        'level' => 'error'
    ],
],

You can follow the steps here to create an incoming webhook for your channel.

Levels

Monolog levels are used to set the message color and icon

Level Name	Level Value	Color	Emoji
DEBUG	100	#91C4EB	🔍
INFO	200	#91C4EB	ℹ
NOTICE	250	#99cc33	📝
WARNING	300	#ffcc00	⚠
ERROR	400	#cc3300	🐛
CRITICAL	500	#cc3300	❌
EMERGENCY	600	#cc3300	🚨

Usage

Simply, using Laravel Log facade

Log::channel('mattermost')->error('Something went wrong', ['user_id' => 5]);

Will send the following message to your mattermost channel:

⚠ Warning: When you log to the mattermost channel make sure that the level is greater than or equals the one defined in config/logging.php

And there you have it! A simple implementation to send log records to a Mattermost channel.

Preventing User Enumeration Attack in Laravel Apps

Muhammad Hassan — Fri, 13 May 2022 13:42:30 +0000

User enumeration is a brute-force technique that is used to collect or verify valid users' credentials. It belongs to the Identification and Authentication Failures category (AKA broken authentication) which came in 7th place on the Top 10 Web Application Security Risks 2021 by OWASP down from the 2nd place in the 2017 version. It can also be part of phishing attack or other brute-force attacks like credential stuffing and password spraying.
Bear in mind that user enumeration vulnerabilities are not exclusive for web applications, it can be found in any system that requires authentication.

Attacking Scenarios

The malicious actor will be basically looking for differences in the authentication server's response, in terms of response time and body, based on the authenticity of submitted credentials. This can happen while using one of the following functionalities:

Login
Registration
Password Reset

Laravel Authentication

Laravel provide us with robust solutions and starter kits for authentication so let's start by creating a new Laravel 9 project and install Jetstram

laravel new user-enum

composer require laravel/jetstream

and for simplicity we will use SQLite 3.36.0

DB_CONNECTION=sqlite
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE="[PROJECT_PATH]/user-enum/database/database.sqlite"
DB_USERNAME=root
DB_PASSWORD=

Login

Out of the box, the error message is consistent whether you entered an incorrect email or password.

Password Reset

Here, the error message discloses that a user doesn't exist in the system so, as we mentioned, we need to make the response message and time consistent.

Moreover, a malicious user can validate user email address existence by sending the reset password request twice. If the email address is valid, on the second attempt a different error message is returned

Under the hood, Jetstream is using Fortify which is a frontend-agnostic authentication implementation. Our first stop will be the controller registered by Fortify for password reset.

php artisan route:list
  ...
  POST  forgot-password ............. password.email › Laravel\Fortify › PasswordResetLinkController@store

Let's see what the method Laravel\Fortify\PasswordResetLinkController::store do:

First, it validates the submitted email address.
Then the password broker tries to send the reset email to the user of the submitted email address.
Based on the return value of the \Illuminate\Contracts\Auth\PasswordBroker::sendResetLink() method, the response is determined hence the user information is disclosed.

public function store(Request $request): Responsable
{
    $request->validate([Fortify::email() => 'required|email']);

    // We will send the password reset link to this user. Once we have attempted
    // to send the link, we will examine the response then see the message we
    // need to show to the user. Finally, we'll send out a proper response.
    $status = $this->broker()->sendResetLink(
        $request->only(Fortify::email())
    );

    return $status == Password::RESET_LINK_SENT
                ? app(SuccessfulPasswordResetLinkRequestResponse::class, ['status' => $status])
                : app(FailedPasswordResetLinkRequestResponse::class, ['status' => $status]);
}

To fix this, we will create our controller at App\Http\Controller\Auth\PasswordResetLinkController that will extend Fortify's controller. The difference here is that instead of returning the invalid email address error, we will log it and return the same SuccessfulPasswordResetLinkRequestResponse message.

public function store(Request $request): Responsable
{
    $request->validate([Fortify::email() => 'required|email']);
    $email = $request->only(Fortify::email());
    $status = $this->broker()->sendResetLink($email);

    if ($status !== Password::RESET_LINK_SENT) {
        Log::error(__($status, [], 'en'), ['email' => $email]);
    }

    return app(SuccessfulPasswordResetLinkRequestResponse::class, ['status' => Password::RESET_LINK_SENT]);
}

Then we need to define our reset-password route in routes/web.php that will point to the above controller

Route::post('reset-password', 'App\Http\Controllers\Auth\PasswordResetLinkController@store')
    ->name('password.email')
    ->middleware('guest');

At this point, the response message will be the same regardless of the email validity. But, what about the response time? as you can see in the below screenshot, the first request, with an invalid email, took less than a second, while the one with a valid email took over 6 seconds!

One way to reduce the gap between the two scenarios is to make the Illuminate\Auth\Notifications\ResetPassword notification queueable. So, again we will create our version of this notification at App\Notifications\ResetPassword and make it so. Check the Laravel docs for more information on queuing notifications

<?php

namespace App\Notifications;

use Illuminate\Auth\Notifications\ResetPassword as CoreResetPassword;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;

class ResetPassword extends CoreResetPassword implements ShouldQueue
{
    use Queueable;
}

Then we will override the Illuminate\Auth\Passwords\CanResetPassword::sendPasswordResetNotification() method in the App\Models\User model

public function sendPasswordResetNotification($token)
{
    $this->notify(new ResetPassword($token));
}

Registration

I think you already know the answer to this. Yes, the registration response will disclose whether the user email exist or not.

To make the response consistent, we will enable user email verification so that an email is sent in both scenarios

Then publish Fortify resources so that its actions become editable. Specifically App\Actions\Fortify\CreateNewUser

php artisan vendor:publish --provider="Laravel\Fortify\FortifyServiceProvider"

The changes is quite simple, first, we remove the unique rule from the email input. Then, if a user with the submitted email address exist, an email will be sent to notify him/her.

public function create(array $input): ?User
{
    Validator::make($input, [
        'name' => ['required', 'string', 'max:255'],
        'email' => ['required', 'string', 'email', 'max:255'],
        'password' => $this->passwordRules(),
        'terms' => Jetstream::hasTermsAndPrivacyPolicyFeature() ? ['accepted', 'required'] : '',
    ])->validate();

    if ($user = User::whereEmail($input['email'])->first()) {
        $user->notify(new AlreadyHaveAccount());
        return ;
    }

    return User::create([
        'name' => $input['name'],
        'email' => $input['email'],
        'password' => Hash::make($input['password']),
    ]);
}

And the App\Notifications\AlreadyHaveAccount notification will be

<?php

namespace App\Notifications;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Notifications\Messages\MailMessage;
use Illuminate\Notifications\Notification;
use Illuminate\Support\Facades\Lang;

class AlreadyHaveAccount extends Notification implements ShouldQueue
{
    use Queueable;

    public function __construct()
    {
    }

    public function via(mixed $notifiable): array
    {
        return ['mail'];
    }

    public function toMail(mixed $notifiable): MailMessage
    {
        return (new MailMessage)
            ->subject('New Registration Attempt with Your Email Address')
            ->line('You are receiving this email because we received a registration request with your registered email address.')
            ->action('Login Instead', route('login'))
            ->line(Lang::get('If you did not try to register a new account, no further action is required.'));
    }
}

Next, we will create a job that accept CreateNewUser action and the submitted input to make the response time consistent

<?php

namespace App\Jobs;

use Illuminate\Auth\Events\Registered;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
use Laravel\Fortify\Contracts\CreatesNewUsers;

class RegisterUser implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(private CreatesNewUsers $creator, private array $input)
    {
        //
    }

    public function handle()
    {
        $user = $this->creator->create($this->input);

        if ($user) {
            event(new Registered($user));
        }
    }
}

And finally, create a controller for registration, like we did with resetting passwords, and make the register route point to it

<?php

namespace App\Http\Controllers\Auth;

use App\Http\Responses\RegisterResponse;
use App\Jobs\RegisterUser;
use Illuminate\Http\Request;
use Laravel\Fortify\Contracts\CreatesNewUsers;
use Laravel\Fortify\Http\Controllers\RegisteredUserController as FortifyRegisteredUserController;

class RegisteredUserController extends FortifyRegisteredUserController
{
    public function store(Request $request, CreatesNewUsers $creator): RegisterResponse
    {

        RegisterUser::dispatch($creator, $request->all());

        return app(RegisterResponse::class);
    }
}

Route::post('register', 'App\Http\Controllers\Auth\RegisteredUserController@store')
    ->middleware('guest');

Now login, reset password and registration will never disclose existing users information and our app is protected against user enumeration attacks ✌.

Adding PHPUnit Test Log and Coverage to GitLab CI/CD Pipeline

Muhammad Hassan — Fri, 22 Apr 2022 22:33:34 +0000

In this tutorial we are going to setup a GitLab CI/CD job that can run your PHPUnit test suite and extract a testing report plus the overall coverage. First, we need to setup our server and install the required tools. DigitalOcean has many useful tutorials and we are going to use some of them for the initial setup.

Prerequisites

An Ubuntu 20.04 server setup by following this tutorial
Install Docker following this tutorial
Finally, installing Docker Compose by following this tutorial

Server Setup

Now that the server’s initial setup is complete, our next steps will be: installing GitLab runner, register a runner for your project and create a user for deployment.

Installing GitLab Runner

1- Adding the official gitlab-runner repo and inspecting the security of the installing script

   curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh > script.deb.sh
   less script.deb.sh

2- Running the installer

   sudo bash script.deb.sh

3- Install gitlab-runner service

   sudo apt install gitlab-runner

4- Check the service status

   systemctl status gitlab-runner

The output should be something like this

   Output
   ● gitlab-runner.service - GitLab Runner
      Loaded: loaded (/etc/systemd/system/gitlab-runner.service; enabled; vendor preset: enabled)
      Active: active (running) since Mon 2020-06-01 09:01:49 UTC; 4s ago
    Main PID: 16653 (gitlab-runner)
       Tasks: 6 (limit: 1152)
      CGroup: /system.slice/gitlab-runner.service
              └─16653 /usr/lib/gitlab-runner/gitlab-runner run --working-directory /home/gitlab-runner --config /etc/gitla

Register a Runner for Your GitLab Project

1- In your GitLab project, navigate to Settings > CI/CD > Runners.

2- In the Specific Runners section, you’ll find the registration token and the GitLab URL. Copy both as we’ll need them for the next command.

3- Now in the terminal, register the runner by running

   sudo gitlab-runner register -n --url https://your_gitlab.com --registration-token project_token --executor shell --description "Staging Shell Runner" --tag-list deployment

This seems like a lot of options but they’re pretty easy to understand:

-n executes the register command non-interactively.
--url is the GitLab URL from step 2.
--registration-token is the token you copied from the runners page in step 2.
--executor is the executor type, we are using shell executer here which is a simple executor that you use to execute builds locally on the machine where GitLab Runner is installed.
--description is the runner’s description, which will show up in GitLab.
--tag-list is a list of tags assigned to the runner. Tags can be used in a pipeline configuration to select specific runners for a CI/CD job. The deployment tag will allow you to refer to this specific runner to execute the deployment job.

4- The output of the above command will return an output like this:

   Output
   Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

And the runner will show up in your project’s Settings > CI/CD > Runners

Create Deployment User

1- Create a new user

   sudo adduser deployer

2- Add user to docker group to permit deployer to execute the docker command, which is required to perform the deployment

   sudo usermod -aG docker deployer

3- Create SSH key for deployer

Switch to the deployer user

   su deployer

Then generate a 4096-bit SSH key

   ssh-keygen -b 4096

> ⚠ Do not choose a password for your key or you will have to enter it with each job. This is not possible since our runner is non-interactive

Add the new key to the authorized keys

```bash
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
```

4- Storing the private key in a GitLab CI/CD variable

First, get the private key be executing

   cat ~/.ssh/id_rsa

Copy the output and navigate to Settings > CI / CD > Variables and click Add Variable

fill the variable form like this

Key: ID_RSA
Value: Paste your SSH private key from your clipboard (including a line break at the end).
Type: File
Environment Scope: All (default)
Protect variable: Checked
Mask variable: Unchecked

Create another variable for your server IP address

Key: SERVER_IP
Value: your_server_IP
Type: Variable
Environment scope: All (default)
Protect variable: Checked
Mask variable: Checked

And the last variable is for the user

Key: SERVER_USER
Value: deployer
Type: Variable
Environment scope: All (default)
Protect variable: Checked
Mask variable: Checked

Configuring `.gitlab-ci.yml` File

Next, we will be prepare the docker file for testing environment, the application service in docker compose file and finally PHPUnit job in .gitlab-ci.yml

Application Docker file

In your app docker file we will need to install XDebug extension to collect the testing coverage report and create two new files: phpunit-report.xml and phpunit-coverage.xml for testing report and testing coverage.

We will create the file in ./docker/testingApp.dockerfile with minimal configuration. It should be something like this.

FROM php:8.1.3-fpm-alpine

WORKDIR /var/www/

# Install alpine packages
RUN apk add --no-cache --update # Add your packages

# Install php extensions
RUN docker-php-ext-install # Add the PHP extension you need

# Install XDebug
RUN pecl install xdebug \
    && docker-php-ext-enable xdebug 

# Copy existing application directory contents
COPY --chown=www-data:www-data . .

RUN touch phpunit-report.xml phpunit-coverage.xml
RUN chmod 777 phpunit-report.xml phpunit-coverage.xml

USER www-data

Application Service

The app service in ./docker/docker-compose-testing.yml will have two volumes: one for the tests directory and the other is ./docker/php/conf.d/xdebug.ini that will contain the basic XDebug configuration.

The app service should look like this:

version: "3"
services:
  app:
    container_name: "app-testing"
    build:
      context: ../
      dockerfile: ./docker/testingApp.dockerfile
    volumes:
      - ./php/conf.d/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
    working_dir: /var/www

And xdebug.ini is quite minimal, we just set enable the coverage mode but you can enable multiple modes at the same time. Learn more about XDebug modes from the documentation

zend_extension=xdebug

[xdebug]
xdebug.mode=coverage

PHPUnit Job

In .gitlab-ci.yml we will create a job for PHPUnit that will have the deployment tag so that it uses our runner and extract the required artifacts for GitLab to display test reports.

The job will be

phpunit:
  stage: test
  tags:
    - deployment
  before_script:
    - docker-compose -p my-project -f docker/docker-compose-testing.yml build
    - docker-compose -p my-project -f docker/docker-compose-testing.yml up -d
    - docker exec $CONTAINER_NAME php artisan migrate
    - docker exec $CONTAINER_NAME php artisan db:seed
  script:
    - docker exec -t $CONTAINER_NAME vendor/bin/phpunit --do-not-cache-result --log-junit phpunit-report.xml --coverage-cobertura phpunit-coverage.xml --coverage-text --colors=never
    - docker cp $CONTAINER_NAME:/var/www/phpunit-report.xml ./
    - docker cp $CONTAINER_NAME:/var/www/phpunit-coverage.xml ./
  after_script:
    - docker-compose -p my-project -f docker/docker-compose-testing.yml down
  artifacts:
    when: always
    reports:
      junit: phpunit-report.xml
      coverage_report:
        coverage_format: cobertura
        path: phpunit-coverage.xml
  coverage: '/^\s*Lines:\s*\d+.\d+\%/'
  only:
    - merge_requests
    - main
    - develop

You should notice that we build our containers using docker-compose-testing.yml, run the DB migrations and seeder then run our test suit with a few options:

docker exec -t $CONTAINER_NAME vendor/bin/phpunit --do-not-cache-result --log-junit phpunit-report.xml --coverage-cobertura phpunit-coverage.xml --coverage-text --colors=never

--do-not-cache-result to disable test result caching.
--log-junit phpunit-report.xml specify the test log format and the output file.
--coverage-cobertura phpunit-coverage.xml specify the coverage full report format and the output file.
--coverage-text generate code coverage report in text format.
--colors=never disable colors in the output to make it easier to extract the coverage percentage from the command output.

Then we copy the generated reports from inside the container to the pipeline namespace to be used as job artifacts

docker cp $CONTAINER_NAME:/var/www/phpunit-report.xml ./
docker cp $CONTAINER_NAME:/var/www/phpunit-coverage.xml ./

The job will have two artifacts of type reports the first is the a junit for test log and a cobertura report for the test coverage.

artifacts:
    when: always
    reports:
      junit: phpunit-report.xml
      coverage_report:
        coverage_format: cobertura
        path: phpunit-coverage.xml

ℹ The report formats and files’ extensions are specified by GitLab

Project Configuration

At this point we have created a job for PHPUnit that we run on our Staging Shell Runner that we registered on the staging server. GitLab will be able to display a test report that include some helpful information like the total execution time of the test suite and the success rate. It will also show the test coverage on the jobs and in the merge request overview.

To go one step further, we can track the test coverage history and add coverage badge to the project

Test Coverage History Using Project Settings (Deprecated in GitLab 14.9)

Navigate to Settings > CI/CD > General Pipelines and in the Test Coverage Parsing field add the same regular expression that we used in the job ^\s*Lines:\s*\d+.\d+\%

Test Coverage Badge

Navigate to Settings > General Settings > Badges and click Add Badge and fill the form as follows:

Name: PHPUnit Coverage
Link: https://gitlab.com/[PROJECT_PATH]/-/commits/[BRANCH_NAME]
Badge Image URL: https://gitlab.com/[PROJECT_PATH]/badges/[BRANCH_NAME]/coverage.svg

Result

You can see a test report in your pipeline

Navigate to Analytics > Repository > Code Coverage Statistics to see the history of test coverage

The effect of each merge request on the test coverage can be found in the merge request overview page.

Laravel Static Code Analysis with PHPStan

Muhammad Hassan — Sat, 26 Feb 2022 12:51:24 +0000

Code analysis is the process of testing and evaluating a program either statically or dynamically.

Dynamic analysis is the process of testing and evaluating a program — while software is running. It addresses the diagnosis and correction of bugs, memory issues, and crashes of a program during its execution. While static code analysis is a method of evaluating a program by examining the source code before its execution. It is done by analyzing a set of code against a set of coding rules.

Static analysis takes place before software testing begins. It guarantees that the code you pass on to testing is the highest quality possible. It also provide an automated feedback loop so the developers will know early on which in turn make it easier, and cheaper, to fix those problems.

Code analysis is the process of testing and evaluating a program either statically or dynamically.

In this tutorial we are going to discuss:

Code Analysis Jargons
- Measurements
- Code Structure
- Complexity
- Security Issues
What Does PHPStan Bring?
- Running PHPStan for the First Time
- Rule Levels
How to Use PHPStan?
- Installation
- Configuration File
- Ignoring Errors
- The Baseline
- Adding PHPStan to your CI/CD
Limitations of Static Analysis
Helpful Links

Code Analysis Jargons

Before moving to PHPStan, or any other tool, we need to be familiar with the terms that are commonly used in the code analyzation world. You can also think of them as what the tools will be looking for in your software.

Measurements

- Naming
Checking if variables and methods’ names, are they too short or too long? Do they follow a naming convention like camel-case?

- Type Hinting
Some tools can suggest a name consistent with the return type. For example a getFoo() method that returns a boolean is better be named isFoo().

- Lines of Code
Measures the line of codes in your class or method against a maximum value. In addition to the number of method's parameter or class' number of public methods and properties.

- Commented Code
Most of the time no commented out block of code will be allowed, as long as you are using a version control system, you can remove unused code and if needed, it's recoverable.

- Return Statements
How many return statements do you have through out your method? Many return statements make it difficult to understand the method.

- Return Types
Makes sure that return type matches the expected. Having many return types possibilities confuses the analyzers.

Code Structure

- Dedicated Exceptions
Ensure the use of dedicated exceptions, instead of generic run-time exceptions, that can be cached by client code.

- No Static Calls
Avoid using static calls in your code and instead use dependency injection. Factory methods is the only exception.

- DRY
Checks for code duplication either in repeating literal values or whole blocks of code.

Complexity

Having a lot of control structures in one method AKA the pyramid of doom. Possible fixes include:

Early return statements
Merging nested if statements in combination with helper functions that make the condition readable

Security Issues

- Cipher Algorithms
Ensure the use cryptographic systems resistant to cryptanalysis, which are not vulnerable to well-known attacks like brute force attacks for example.

- Cookies
Always create sensitive cookies with the “secure” flag so it’s not sent over an unencrypted HTTP request.

- Dynamic Execution
Some APIs allow the execution of dynamic code by providing it as strings at runtime. Most of the time their use is frowned upon as they also increase the risk of code injection.

What Does PHPStan Bring?

Running PHPStan for the First Time

I have been using SonarQube for quite long time but when I first came across PHPStan repo I found this arguable claim...

PHPStan focuses on finding errors in your code without actually running it. It catches whole classes of bugs even before you write tests for the code. It moves PHP closer to compiled languages in the sense that the correctness of each line of the code can be checked before you run the actual line.
So to put it to the test, I installed PHPStan in an application that has been analyzed with SonarQube since day one and the results were impressive

PHPStan has many rule levels, and as you can see, the higher the level we select the more errors we get with a maximum of 516 errors. Now the question is, which level should we select? Well first we need to know what are the rules of each level.

Rule Levels

Level	Name	Details
00	Basic Checks	Checks for Unknown classes, unknown functions, unknown methods called on $this, wrong number of arguments passed to those methods and functions, always undefined variables.
01	`$this` Unknowns	Possibly undefined variables, unknown magic methods and properties on classes with `__call` and `__get`.
02	Methods	Unknown methods checked on all expressions (not just `$this`), validating PHPDocs.
03	Types	Checks for return types, types assigned to properties.
04	Dead Code	Basic dead code checking - always false `instanceof` and other type checks, dead `else` branches, unreachable code after `return`; etc.
05	Arguments	Checking types of arguments passed to methods and functions.
06	Type Hints	Reports missing type hints.
07	Union Types	Reports partially wrong union types, if you call a method that only exists on some types in a union type, level 7 starts to report that.
08	Nullable Types	Report calling methods and accessing properties on nullable types.
09	Mixed Type	Be very strict about the mixed type, the only allowed operation you can do with it is to pass it to another mixed.

How to Use PHPStan?

Installation

To use PHPStan with Laravel we are going to use Larastan extension. Extensions are useful when there are subjective bugs or to accommodate to a certain framework while taking advantage of PHPStan capabilities.

First we install the package with composer

   composer require nunomaduro/larastan:^2.0 --dev

Note: This version requires PHP 8.0+ and Laravel 9.0+

Then you can start analyzing your code with the console command using the default configuration of PHPStan

   ./vendor/bin/phpstan analyse app --memory-limit=25

Here we specified the path that we want to analyze app and the memory limit 25 MB. You can find all the options of the command line here.

Configuration File

PHPStan uses configuration file, phpstan.neon or phpstan.neon.dist, that allows you to:

Define the paths that will be analyzed.
Set the rule level.
Exclude paths.
Include PHPStan extensions.
Ignore errors.
Define the maximum number of parallel processes

Here is an example of a simple configuration file which by default lives in the root directory of your application but you can learn more from the configuration reference.

includes:
    - ./vendor/nunomaduro/larastan/extension.neon

parameters:

    paths:
        - app
        - config
        - database
        - routes

    # The level 9 is the highest level
    level: 5

    ignoreErrors:
        - '#PHPDoc tag @var#'

    parallel:
        maximumNumberOfProcesses: 4

    noUnnecessaryCollectionCall: false
    checkMissingIterableValueType: false

Ignoring Errors

Most probably, you are going to need to ignore some errors which is luckily allowed in two different ways:

Inline using PHPDoc tags

   function () {
       /** @phpstan-ignore-next-line */
       echo $foo;

       echo $bar /** @phpstan-ignore-line */
   }

From the configuration file and this is actually more clean

     parameters:

         ignoreErrors:

             -
                 message: 'Access to an  undefined property [a-zA-Z0-9\_]+::\$foo'
                 path: some/dir/someFile.php
             -
                 message: '#Call to an undefined method [a-zA-Z0-9\_]+::doFoo()#'
                 path: other/dir/DifferentFile.php
                 count: 2 # optional, and it will ignore the first two occurances of the error
          -
                 message: '#Call to an undefined method [a-zA-Z0-9\_]+::doBar()#'
                 paths:
                     - some/dir/*
                     - other/dir/*

The Baseline

Introducing PHPStan to the CI pipeline, increasing strictness level or upgrading to a newer version can be overwhelming. PHPStan allows you to declare the currently reported list of errors as “the baseline” and stop reporting them in subsequent runs. It allows you to be interested in violations only in new and changed code.

If you want to export the current list of errors and use it as the baseline, run PHPStan with --generate-baseline option

./vendor/bin/phpstan analyse --memory-limit=25 --generate-base

Note: We dropped the path option from the example in installation as it is now being set in the config file.

It will generate the list of errors with the number of occurrences per file and saves it in phpstan-baseline.neon. Finally we add the baseline file to our includes

includes:
    - ./vendor/nunomaduro/larastan/extension.neon
    - phpstan-baseline.neon

Adding PHPStan to Your CI/CD

Adding PHPStan to the CI/CD pipeline and running it regularly on merge requests and main branches will increase your code quality. In addition to helping in code review.

Embed this snippet in your gitlab-ci.yml file and a code quality report will be generated for any merge request, changes to develop or master branches in addition to release and hotfix branches.

stages: 
  - staticanalysis - 

phpstan:
  stage: staticanalysis
  image: composer
  before_script:
    - composer require nunomaduro/larastan:1.0.2 --dev --no-plugins --no-interaction --no-scripts --prefer-dist --ignore-platform-reqs
  script:
    - vendor/bin/phpstan analyse --no-progress --error-format gitlab > phpstan.json
  cache:
    key: ${CI_COMMIT_REF_SLUG}-composer-larastan
    paths:
      - vendor/
  artifacts:
    when: always
    reports:
      codequality: phpstan.json
  allow_failure: true
  dependencies:
    - php-cs-fixer
  needs: 
    - php-cs-fixer
  only:
    - merge_requests
    - master
    - develop
    - /^release\/[0-9]+.[0-9]+.[0-9]$/
    - /^hotfix\/[0-9]+.[0-9]+.[0-9]$/

Limitations of Static Analysis

Static analysis is not a substitute for testing, they are different tools targeting different domains in the development lifecycle, and it has some limitation:

No Understanding of Developer Intent

  function calculateArea(int $length, int $width): int
  {
      $area = $length + $width;

      return;
  }

In the above function, a static code analysis tool might detect that the returned value does not match the defined type but it cannot determine that the function is semantically wrong!

Some rules are subjective depending on the context.
False Positives and False Negatives.

DEV Community: Muhammad Hassan

PHP Attributes and Metaprogramming

Introduction

Metaprogramming

Decorator

Aspect-Oriented Programming

Reflection API

Attributes

Syntax

Usage

Client Code

Real-Life Example

Config Attribute Definition

Resolving Config Attribute

Attributes Misuse

PHP Generics in Laravel 11

What are Generics?

Generics Syntax

Types of PHP Generics

Generic Function

Generic Class

Generic Interface

Generic Trait

Preserving Genericness

Final Thoughts

Creating Refresh Tokens with Laravel Sanctum

What is a Reference Token?

Advantages of Reference Tokens

Why Refresh Tokens Are Needed?

Issuing Refresh Tokens with Sanctum

1. Configure Time-to-Live Values

2. Overriding Sanctum Service Provider

3. Define Token Abilities

4. Assign the Ability Middleware to Routes

Using ULID in Laravel Framework

Eloquent Models

Str Facade

Using Unique Identifiers as Primary Key in MySQL

Using Unique Identifiers as Primary Key in MySQL

UUIDs

UUIDs are Pseudo Random

UUIDs Size

ULIDs

Sending Laravel Logs to Mattermost Channels

Installation

Configuration

Levels

Usage

Preventing User Enumeration Attack in Laravel Apps

Attacking Scenarios

Laravel Authentication

Login

Password Reset

Registration

Adding PHPUnit Test Log and Coverage to GitLab CI/CD Pipeline

Prerequisites

Server Setup

Installing GitLab Runner

Register a Runner for Your GitLab Project

Create Deployment User

Configuring .gitlab-ci.yml File

Application Docker file

Application Service

PHPUnit Job

Project Configuration

Test Coverage History Using Project Settings (Deprecated in GitLab 14.9)

Test Coverage Badge

Result

Laravel Static Code Analysis with PHPStan

Code Analysis Jargons

Measurements

Code Structure

Complexity

Security Issues

What Does PHPStan Bring?

Running PHPStan for the First Time

Rule Levels

How to Use PHPStan?

Installation

Configuration File

Resolving `Config` Attribute

Configuring `.gitlab-ci.yml` File