The system requests characters in random positions each time I log in, which is quite interesting. Passwords are supposed to be stored as salted hashes, and with that, only the full password can be verified. So, what is happening here?

Advantages

Partial password authentication was adopted mainly in response to a combination of security threats and regulatory pressure, primarily in the U.S. and Europe during the early-to-mid 2000s.

Keystroke Logging Malware

Keystroke Logging Malware was a major catalyst due to the rise of keyloggers that recorded every keystroke. If a user entered their full password, attackers could capture it completely. Partial password entry countered this by only requesting certain characters, so even if a keylogger captured them, it wouldn't have the full password, and the next login would require different positions.

Shoulder Surfing Protection

Shoulder surfing protection functions similarly. Observers or cameras only capture a few characters per session, requiring multiple observations to track the requested positions each time.

Phishing Mitigation

Phishing mitigation is subtle but effective. If a fake site asks for your full password, it gains everything. However, if the real bank only requests partial characters, a phishing site must either ask for the full password, which should alert users, or request a few characters, limiting what they capture. It's not foolproof, but it increases security.

Backend Implementation

With standard password authentication, you store a salted hash (e.g., bcrypt) and compare. But hashing is a one-way, all-or-nothing operation — you can't verify the 3rd character of a password from a bcrypt hash. So partial password verification requires a fundamentally different storage and verification strategy.

1. Encrypted Plaintext Storage

The most straightforward approach. You store the password encrypted (not hashed) using a symmetric key (e.g., AES-256), managed via an HSM or a secrets manager.

Verification flow:

1. Server generates a random set of character positions (e.g., positions 2, 5, 8).

2. User submits those characters.

3. Server decrypts the stored password, extracts the characters at those positions, and compares.

4. Plaintext is discarded from memory immediately.

Tradeoffs:

Simple to implement, but the password is technically recoverable. If the encryption key is compromised, all passwords are exposed. This is why the key must live in an HSM with strict access controls. Many UK banks use this model.

2. Store Individual Character Hashes

You hash each character (or each character + its position) independently and store them all.

For a password s3cur3, you'd store something like:

position_0: hash("s" + salt + "0")
position_1: hash("3" + salt + "1")
position_2: hash("c" + salt + "2")

Verification flow:

1. Server picks random positions, sends them to the client.

2. User submits the characters.

3. Server hashes each submitted character with the corresponding positional salt and compares.

Tradeoffs:

No reversible encryption is needed. However, each character hash has a small keyspace, making brute-force attacks easy unless a costly hash function (like high-cost bcrypt or Argon2) is used per character. Even then, attackers with the database can crack positions offline with some effort. Using an HSM-held pepper can make offline attacks infeasible without it.

3. Shamir's Secret Sharing / Threshold Schemes

A more cryptographically elegant approach. You treat the password (or a key derived from it) as a secret and split it into shares using a threshold scheme.

Setup:

1. User registers with full password.

2. Server derives a secret from the password and splits it into n shares (one per character position) using a (k, n) threshold scheme, where k is the number of characters you'll challenge.

3. Shares are stored server-side.

Verification flow:

1. Server challenges the user for k positions.

2. Each correct character allows reconstruction of the corresponding share.

3. If k valid shares are provided, the secret is reconstructed and verified against a stored hash of the secret.

Tradeoffs:

Mathematically strong — fewer than k correct characters reveal zero information about the secret. But it's complex to implement correctly, and key management during registration is critical.

4. Pre-computed Challenge-Response Sets

At registration, you pre-generate all (or many) possible challenge combinations and store a hash for each.

For example, if you always ask for 3 of 10 characters, there are C(10,3) = 120 combinations. For each combination, you concatenate those characters and store a salted hash.

Verification flow:

1. Server picks a combination, looks up the corresponding hash.

2. User submits the characters.

3. Server hashes the submission and compares.

Tradeoffs:

You get proper hashing (bcrypt/Argon2) with no reversibility. But storage grows combinatorially. For 3 of 10, 120 hashes is manageable. For 4 of 20, it's C(20,4) = 4,845 — still feasible but heavier. Each hash needs its own salt, and password changes require regenerating the entire set. This is arguably the best balance of security and functionality for moderate password lengths.

Is it Still Relevant?

Honest answer: partial password authentication is a legacy technique that's being actively phased out. It was already niche (primarily UK banks and a few European financial institutions), and the industry has moved decisively past it.

Why it's dying out

The fundamental problem is that partial passwords solve a narrow threat (keyloggers capturing the full password in one session) while introducing significant backend complexity and weaker security properties compared to modern alternatives. Every design we discussed requires either storing passwords reversibly, dealing with tiny per-character keyspaces, or managing combinatorial storage — all of which are worse trade-offs than what's now available.

What replaced it

The shift is toward eliminating shared secrets entirely. Passwords are responsible for 80% of data breaches, and passwordless authentication removes that attack surface. Here's what the landscape looks like now:

Passkeys (FIDO2/WebAuthn)

The clear winner. They use asymmetric cryptography — a private key stays on the user's device, a public key sits on the server. There's nothing to phish, nothing stored server-side that's useful to an attacker, and nothing for the user to remember. As of Q1 2026, over 340 million banking customers worldwide authenticate using passkeys or other FIDO2-compliant methods, with adoption accelerating 180% year-over-year. Major banks have gone all-in: HSBC launched passkey authentication across 14 markets simultaneously, achieving 41 million passkey users — a 60% adoption rate in just six months. Nordea became the first bank to fully deprecate password authentication, and as of January 2026, new customers can only set up passkey authentication.

Regulatory pressure is making this mandatory, not optional.

The UAE Central Bank issued a directive requiring all financial institutions to eliminate SMS and email OTPs by March 2026. NIST's SP 800-63-4 now requires that multi-factor authentication must offer a phishing-resistant option, and AAL3 requires hardware-backed non-exportable private keys. India, the Philippines, and the EU all have similar deadlines landing in 2026.

Device-bound biometrics (fingerprint, face recognition) serve as the local unlock for passkeys. The user taps their fingerprint to release the private key — no secret ever crosses the network. Microsoft found that passkey sign-ins take only 8 seconds on average, compared with 69 seconds for traditional password plus second factor.

Adaptive/risk-based authentication layers on top, evaluating contextual signals like device, location, and behavior patterns to dynamically adjust requirements without adding user friction.

Partial password authentication was a clever workaround when keyloggers were a major threat and stronger alternatives were unavailable. Each backend design balanced simplicity, cryptographic rigor, and infrastructure trust, but all shared a weakness: the server held something worth stealing. In 2026, passkeys have rendered this obsolete by eliminating shared secrets at the protocol level—nothing sensitive is stored server-side, nothing useful crosses the network, and nothing needs memorizing. With regulatory mandates enforcing phishing-resistant authentication and over 340 million banking customers using FIDO2/WebAuthn, partial passwords are now a historical curiosity. Today, the solution is passkeys—offering the cryptographic elegance that Design 3 aimed for, but delivered natively.

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).

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.

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

1. 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;
        }
    }
   

2. 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);
    }
}

Resolving Config Attribute

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

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);
}

1. 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.

2. 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.

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);
}

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.

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.

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 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 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:

• 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, some tradeoffs come with using a 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 a 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 the 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 disk in the same order as the index.

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

1. Checks whether the page is already in the buffer pool

2. If the page is not in the buffer pool, InnoDB reads the page from the disk.

3. Write the page to the buffer pool.

4. Insert the new row.

5. 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 a 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 keys 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 a 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 let's assume a table with a UUID primary key and 4 secondary indexes. Considering that each secondary index stores 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:

1. 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.

2. A 16-character random value, encoded using 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:

• It 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

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

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.

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:

1. First, it validates the submitted email address.
2. Then the password broker tries to send the reset email to the user of the submitted email address.
3. 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 ✌.

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.

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

    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 (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.

Dynamic analysis is the process of testing and evaluating a program — while the 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 provides 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 Jargons

Before moving to PHPStan, or any other tool, we need to be familiar with the terms that are commonly used in the code analysis 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 throughout your method? Many return statements make it difficult to understand the method.

- Return Types Makes sure that the 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 are 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 of 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 a 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

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.

1. 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+

1. 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 a 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 that 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 are luckily allowed in two different ways:

1. Inline using PHPDoc tags

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

2. From the configuration file and this is 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 the 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 limitations:

• 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.

Helpful Links

• Laravel-specific rules

• Errors to ignore

• PHPDocs usage with PHPStan

• List of analysis tools for different languages