PHP Traits in TypeScript: 4 Idioms That Replace Them

#typescript #php #javascript #types

Book: PHP to TypeScript — A Bridge for Modern PHP 8+ Developers
Also by me: The TypeScript Library — the 5-book collection
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

A PHP developer opens a TypeScript codebase, finds three classes that all need a timestamps() behaviour, types trait, and gets a red squiggle. There is no such keyword. There never was. The PHP reflex says I will pull the methods into a base class and extend, then remembers TypeScript has single inheritance too. The reflex stalls.

The honest answer is that TypeScript will never give you a trait keyword. The language design pulls in a different direction. What it gives you instead is four shapes that cover almost every case a PHP trait covers, with trade-offs you can actually see at the call site. Pick the one that matches the intent of the trait, not its syntax.

Here is one PHP trait. Then four TypeScript rewrites of the same behaviour. Then a decision rule.

The trait we are translating

<?php
declare(strict_types=1);

trait HasTimestamps
{
    private ?DateTimeImmutable $createdAt = null;
    private ?DateTimeImmutable $updatedAt = null;

    public function touch(): void
    {
        $now = new DateTimeImmutable();
        $this->createdAt ??= $now;
        $this->updatedAt = $now;
    }

    public function age(): int
    {
        if ($this->createdAt === null) {
            return 0;
        }
        return (new DateTimeImmutable())
            ->getTimestamp() - $this->createdAt->getTimestamp();
    }
}

final class Post
{
    use HasTimestamps;
    public function __construct(public string $title) {}
}

final class Comment
{
    use HasTimestamps;
    public function __construct(public string $body) {}
}

Post and Comment get touch() and age() for free. They share the two private fields. No inheritance. The trait is copied in at compile time and the class behaves as if you had written the methods directly. That last sentence is doing all the work — that is the contract you are translating.

Idiom 1: mixin function returning an intersection type

The closest TypeScript shape to a trait. A function that takes a base class and returns a subclass with extra methods. The type system carries the intersection so the call site sees both the base and the mixed-in surface.

type Constructor<T = {}> = new (...args: any[]) => T;

function HasTimestamps<TBase extends Constructor>(Base: TBase) {
  return class extends Base {
    private createdAt: Date | null = null;
    private updatedAt: Date | null = null;

    touch(): void {
      const now = new Date();
      this.createdAt ??= now;
      this.updatedAt = now;
    }

    age(): number {
      if (this.createdAt === null) return 0;
      return Math.floor(
        (Date.now() - this.createdAt.getTime()) / 1000,
      );
    }
  };
}

class PostBase {
  constructor(public title: string) {}
}

class Post extends HasTimestamps(PostBase) {}

const p = new Post("Mixins Are Fine");
p.touch();
p.age();

This works. Post has title, touch(), and age(). The compiler types the return of HasTimestamps(PostBase) as Constructor<PostBase> & ExtraStuff, intersected back into a class. The TypeScript handbook documents the exact pattern under Mixins, and it is the one the TypeScript team reaches for when they need one in the compiler.

The rough edge: chain two mixins (HasSlug(HasTimestamps(PostBase))) and the inferred type usually still works. Chain three or four and you start hitting Type instantiation is excessively deep and possibly infinite. The fix is explicit type annotations on each step. Or a manual interface Post extends Slug, Timestamps {} declaration paired with the runtime mixin call. At that point the typing chore is louder than the reuse it bought you.

Static method merging is the second snag. PHP traits can declare static methods and the using class inherits them. TypeScript mixin functions return instance shape cleanly; static merging needs you to type (typeof Base) & { staticThing(): void } separately and assign at runtime. Doable. Ugly.

Idiom 2: composition with a helper class field

The reflex from a Java or C# background. Build a small helper class that owns the behaviour, hold an instance as a field, delegate. No inheritance, no mixin gymnastics.

class Timestamps {
  private createdAt: Date | null = null;
  private updatedAt: Date | null = null;

  touch(): void {
    const now = new Date();
    this.createdAt ??= now;
    this.updatedAt = now;
  }

  age(): number {
    if (this.createdAt === null) return 0;
    return Math.floor(
      (Date.now() - this.createdAt.getTime()) / 1000,
    );
  }
}

class Post {
  readonly timestamps = new Timestamps();
  constructor(public title: string) {}
}

const p = new Post("Composition Is Boring And Good");
p.timestamps.touch();
p.timestamps.age();

The call site is one extra hop: p.timestamps.touch() instead of p.touch(). That hop is the entire trade. You keep your inheritance budget, the methods are explicit, the helper is testable in isolation, and you can swap implementations by swapping the field. The type system does zero gymnastics.

When teams that came from Laravel or Symfony land on a TypeScript codebase, this is what they should reach for first. PHP teams resist it because traits erase the extra hop and that erasure is the feature they liked. TypeScript does not erase the hop. Take the loss, gain the clarity.

Idiom 3: interface plus a small abstract class

When the contract matters more than the reuse. The interface declares the surface; the abstract class supplies one implementation; classes that need different behaviour write their own.

interface Timestamped {
  touch(): void;
  age(): number;
}

abstract class TimestampedBase implements Timestamped {
  private createdAt: Date | null = null;
  private updatedAt: Date | null = null;

  touch(): void {
    const now = new Date();
    this.createdAt ??= now;
    this.updatedAt = now;
  }

  age(): number {
    if (this.createdAt === null) return 0;
    return Math.floor(
      (Date.now() - this.createdAt.getTime()) / 1000,
    );
  }
}

class Post extends TimestampedBase {
  constructor(public title: string) {
    super();
  }
}

This is the path that breaks down in PHP, because PHP's single-inheritance rule means a class extending TimestampedBase cannot also extend EventEmittedBase. That is exactly the limitation traits were invented to dodge. In TypeScript you hit the same single-inheritance ceiling, so this idiom only works for one mixed-in concern per class. After that, you are back to mixin functions or composition.

The reason the idiom still earns its place: when the cross-cutting concern is genuinely a type, the interface catches mistakes that a mixin will not. A function that takes Timestamped will accept Post and Comment and reject the strings. A function that takes a mixin's intersection type will accept anything structurally similar, including objects you did not mean to pass.

Idiom 4: module-level functions taking the host as the first argument

The functional escape hatch. The trait was a method bundle? Stop pretending it had to be on the object.

type WithTimestamps = {
  createdAt: Date | null;
  updatedAt: Date | null;
};

function touch(host: WithTimestamps): void {
  const now = new Date();
  host.createdAt ??= now;
  host.updatedAt = now;
}

function age(host: WithTimestamps): number {
  if (host.createdAt === null) return 0;
  return Math.floor(
    (Date.now() - host.createdAt.getTime()) / 1000,
  );
}

type Post = WithTimestamps & { title: string };

const p: Post = {
  title: "Just Call A Function",
  createdAt: null,
  updatedAt: null,
};

touch(p);
age(p);

No classes. No inheritance ladder. No mixin generics. The structural type WithTimestamps is the contract; any object that has those two fields can be touched. The call site reads touch(p) instead of p.touch() — the same characters, no method-resolution puzzle.

Go developers will recognise this shape instantly. It is also how Rust traits work in practice (the trait method takes &self as the first parameter; calling x.method() is sugar for Trait::method(&x)). For data-shaped values without identity (events, DTOs, query results), this is usually the right choice. PHP devs avoid it because PHP class culture punishes free functions; TypeScript's does not.

Decision rule

Pick by the question the trait was answering.

Mixin function (Idiom 1) when you want the call site to read obj.method(), the host is a class with state, and you might compose more than one cross-cutting concern. Stop at two layers; past that the inferred types start to drown.
Composition with a field (Idiom 2) when the behaviour is testable in isolation, the extra .field hop is fine, and you want to keep your single-inheritance slot for something else. This is the right default.
Interface plus abstract class (Idiom 3) when the type matters as much as the implementation. Use it for the one concern that wins the inheritance slot. Pair it with composition for the rest.
Module-level functions (Idiom 4) when the host is data, not behaviour. DTOs, events, results, query rows. Functions over a structural type beat mixed-in methods when nothing on the object needs this.

Two of these (composition, module-level functions) cost zero TypeScript wizardry. Reach for those first. Reach for mixins only when the ergonomics of obj.method() actually pay for the type-system cost.

What you give up, said plainly

PHP traits give you method-bundle reuse without inheritance and without an extra hop at the call site. The price is conflict-resolution rules (insteadof, as), order-of-definition footguns, and traits that seem like interfaces but are not. TypeScript's four idioms together cover the same surface area, with one of the four winning by being boring. Pick boring when you can.

If your trait was masking the fact that the data should have been a record and the methods should have been functions, Idiom 4 ends the conversation. If it was masking the fact that two concerns should have been one helper class, Idiom 2 ends it. The cases left over for Idiom 1 are smaller than your PHP instincts suggest.

If this was useful

PHP to TypeScript in The TypeScript Library walks the full bridge: traits to mixins, magic methods to proxies, attributes to decorators, generators to async iterators, and the parts of generics PHP did not prepare you for. It is one of five books in the collection:

TypeScript Essentials — entry point. Types, narrowing, modules, async, daily-driver tooling across Node, Bun, Deno, the browser.
The TypeScript Type System — the deep dive. Generics, mapped and conditional types, infer, template literals, branded types.
Kotlin and Java to TypeScript — bridge for JVM developers. Variance, null safety, sealed-to-unions, coroutines to async/await.
PHP to TypeScript — bridge for PHP 8+ developers. The book this post came from.
TypeScript in Production — the production layer. tsconfig, build tools, monorepos, library authoring, dual ESM/CJS, JSR.