PHP Traits Explained — How, Why, and When to Use Them

<?php

// Define a reusable trait that formats timestamps.
// Any class that needs this behaviour can just 'use' it.
trait HasTimestamps {
    // Stores the creation time as a Unix timestamp
    private int $createdAtTimestamp;

    // Called by the using class to record when it was created
    public function setCreatedAt(int $timestamp): void {
        $this->createdAtTimestamp = $timestamp;
    }

    // Returns a human-readable date string from the stored timestamp
    public function getCreatedAt(): string {
        return date('Y-m-d H:i:s', $this->createdAtTimestamp);
    }

    // Returns how long ago this was created, e.g. '3 days ago'
    public function getTimeAgo(): string {
        $seconds = time() - $this->createdAtTimestamp;
        if ($seconds < 60) return $seconds . ' seconds ago';
        if ($seconds < 3600) return round($seconds / 60) . ' minutes ago';
        if ($seconds < 86400) return round($seconds / 3600) . ' hours ago';
        return round($seconds / 86400) . ' days ago';
    }
}

// BlogPost already extends a hypothetical ContentItem parent.
// It needs timestamp behaviour but cannot extend another class.
class BlogPost {
    use HasTimestamps; // Snap the 'timestamps' ability pack onto this class

    public function __construct(
        private string $title
    ) {
        // Record the current time when a post is created
        $this->setCreatedAt(time());
    }

    public function getSummary(): string {
        return "Post: '{$this->title}' — Created: {$this->getCreatedAt()}";
    }
}

// Product is a completely different class but needs the SAME timestamp logic.
class Product {
    use HasTimestamps; // Same trait, totally different class

    public function __construct(
        private string $name,
        private float $price
    ) {
        $this->setCreatedAt(time());
    }

    public function getLabel(): string {
        return "{$this->name} (\${$this->price}) — Listed {$this->getTimeAgo()}";
    }
}

$post = new BlogPost('Understanding PHP Traits');
echo $post->getSummary() . PHP_EOL;

$product = new Product('Mechanical Keyboard', 129.99);
echo $product->getLabel() . PHP_EOL;

// Confirm: BlogPost is NOT an 'instanceof' HasTimestamps
// Traits don't create type relationships
var_dump($post instanceof BlogPost);   // true — it's still a BlogPost
// var_dump($post instanceof HasTimestamps); // Fatal Error — traits can't be used with instanceof

<?php

// Trait for basic console-style logging
trait ConsoleLogger {
    public function log(string $message): void {
        // Outputs a plain text log line
        echo '[CONSOLE] ' . $message . PHP_EOL;
    }

    public function formatEntry(string $message): string {
        return strtoupper($message); // console format: uppercase
    }
}

// Trait for structured JSON-style logging
trait JsonLogger {
    public function log(string $message): void {
        // Outputs a JSON-encoded log line
        echo json_encode(['level' => 'info', 'message' => $message]) . PHP_EOL;
    }

    public function formatEntry(string $message): string {
        return json_encode(['entry' => $message]); // JSON format
    }
}

class ApplicationService {
    use ConsoleLogger, JsonLogger {
        // When there's a conflict, use insteadof to pick a winner
        JsonLogger::log insteadof ConsoleLogger;       // JsonLogger wins for log()
        ConsoleLogger::formatEntry insteadof JsonLogger; // ConsoleLogger wins for formatEntry()

        // Use 'as' to keep the losing version under a new name
        // Now we can still call the ConsoleLogger version of log() via logToConsole()
        ConsoleLogger::log as logToConsole;

        // Change visibility: make formatEntry protected in this class
        // (optional — shown for demonstration)
        ConsoleLogger::formatEntry as protected;
    }

    public function processOrder(int $orderId): void {
        // This calls JsonLogger::log() because we said 'insteadof'
        $this->log("Processing order #{$orderId}");

        // This calls the aliased ConsoleLogger::log() we preserved with 'as'
        $this->logToConsole("Also logging order #{$orderId} to console");
    }
}

$service = new ApplicationService();
$service->processOrder(1042);

echo PHP_EOL;

// Demonstrate using multiple traits cleanly when there's NO conflict
trait SoftDeletes {
    private bool $isDeleted = false;

    public function softDelete(): void {
        $this->isDeleted = true; // marks as deleted without removing from DB
    }

    public function isDeleted(): bool {
        return $this->isDeleted;
    }

    public function restore(): void {
        $this->isDeleted = false; // undo the soft delete
    }
}

trait HasSlug {
    private string $slug = '';

    public function setSlug(string $title): void {
        // Auto-generate a URL-friendly slug from a title
        $this->slug = strtolower(str_replace(' ', '-', preg_replace('/[^a-zA-Z0-9 ]/', '', $title)));
    }

    public function getSlug(): string {
        return $this->slug;
    }
}

// Article uses two traits with no conflicts — clean and simple
class Article {
    use SoftDeletes, HasSlug;

    public function __construct(private string $title) {
        $this->setSlug($title);
    }
}

$article = new Article('How to Use PHP Traits Effectively');
echo 'Slug: ' . $article->getSlug() . PHP_EOL;
echo 'Deleted? ' . ($article->isDeleted() ? 'Yes' : 'No') . PHP_EOL;

$article->softDelete();
echo 'After delete — Deleted? ' . ($article->isDeleted() ? 'Yes' : 'No') . PHP_EOL;

$article->restore();
echo 'After restore — Deleted? ' . ($article->isDeleted() ? 'Yes' : 'No') . PHP_EOL;

<?php

// This trait handles the mechanics of activity logging.
// It deliberately does NOT know the channel name — it demands
// that any using class provide that information.
trait LogsActivity {
    // Abstract method: the using class MUST implement this
    // The trait's log() method will call it to find out where to log
    abstract protected function getLogChannel(): string;

    // Abstract method: forces the using class to define what 'context' means
    abstract protected function getActivityContext(): array;

    // The actual logging logic — uses the abstract methods above
    public function logActivity(string $action): void {
        $channel = $this->getLogChannel();     // provided by the using class
        $context = $this->getActivityContext(); // provided by the using class

        // Build a structured log entry
        $logEntry = [
            'channel'   => $channel,
            'action'    => $action,
            'context'   => $context,
            'timestamp' => date('Y-m-d H:i:s'),
        ];

        // In a real app this would write to a file or logging service
        echo '[LOG:' . strtoupper($channel) . '] '
            . $action
            . ' | Context: ' . json_encode($context)
            . PHP_EOL;
    }
}

// PaymentProcessor uses the trait and satisfies its abstract contracts
class PaymentProcessor {
    use LogsActivity;

    public function __construct(
        private string $merchantId,
        private string $gateway
    ) {}

    // Satisfy the first abstract requirement from the trait
    protected function getLogChannel(): string {
        return 'payments'; // this class logs to the 'payments' channel
    }

    // Satisfy the second abstract requirement from the trait
    protected function getActivityContext(): array {
        return [
            'merchant_id' => $this->merchantId,
            'gateway'     => $this->gateway,
        ];
    }

    public function charge(float $amount, string $currency): void {
        // Trait method called here — it knows nothing about payments,
        // but it knows HOW to log because the class told it what it needs
        $this->logActivity("Charged {$amount} {$currency}");
    }
}

// UserAuthenticator also uses the same trait for a completely different domain
class UserAuthenticator {
    use LogsActivity;

    public function __construct(private string $userId) {}

    protected function getLogChannel(): string {
        return 'auth'; // this class logs to the 'auth' channel
    }

    protected function getActivityContext(): array {
        return ['user_id' => $this->userId];
    }

    public function login(string $ipAddress): void {
        $this->logActivity("User logged in from {$ipAddress}");
    }

    public function logout(): void {
        $this->logActivity('User logged out');
    }
}

$processor = new PaymentProcessor('MERCH-882', 'Stripe');
$processor->charge(49.99, 'USD');
$processor->charge(149.00, 'USD');

echo PHP_EOL;

$auth = new UserAuthenticator('USR-4421');
$auth->login('192.168.1.55');
$auth->logout();

<?php

// Step 1: Define the CONTRACT with an Interface.
// This lets us use instanceof and type hints reliably.
interface Auditable {
    public function getAuditLog(): array;
    public function recordChange(string $field, mixed $oldValue, mixed $newValue): void;
}

// Step 2: Provide the IMPLEMENTATION with a Trait.
// The Trait implements the Auditable interface's methods so
// each class doesn't have to duplicate this logic.
trait AuditableTrait {
    // Stores a running list of all changes made to this object
    private array $auditLog = [];

    // Records a single field change with a timestamp
    public function recordChange(string $field, mixed $oldValue, mixed $newValue): void {
        $this->auditLog[] = [
            'field'      => $field,
            'old_value'  => $oldValue,
            'new_value'  => $newValue,
            'changed_at' => date('H:i:s'), // real app would use Carbon or DateTime
        ];
    }

    // Returns the full audit history for this object
    public function getAuditLog(): array {
        return $this->auditLog;
    }
}

// Step 3: Concrete class implements the Interface AND uses the Trait.
// The Trait satisfies the Interface contract — no duplicate code.
class InvoiceOrder implements Auditable {
    use AuditableTrait; // provides getAuditLog() and recordChange()

    private float $total;
    private string $status;

    public function __construct(
        private int $invoiceId,
        float $initialTotal
    ) {
        $this->total  = $initialTotal;
        $this->status = 'draft';
    }

    public function updateTotal(float $newTotal): void {
        // Record the change BEFORE updating the value
        $this->recordChange('total', $this->total, $newTotal);
        $this->total = $newTotal;
    }

    public function updateStatus(string $newStatus): void {
        $this->recordChange('status', $this->status, $newStatus);
        $this->status = $newStatus;
    }
}

// Step 4: Because InvoiceOrder implements Auditable,
// we can type-hint against the interface — not the concrete class.
function printAuditReport(Auditable $entity): void {
    $log = $entity->getAuditLog();
    if (empty($log)) {
        echo 'No changes recorded.' . PHP_EOL;
        return;
    }
    foreach ($log as $index => $entry) {
        echo sprintf(
            "[%d] Field '%s': '%s' → '%s' at %s\n",
            $index + 1,
            $entry['field'],
            $entry['old_value'],
            $entry['new_value'],
            $entry['changed_at']
        );
    }
}

$invoice = new InvoiceOrder(invoiceId: 5501, initialTotal: 250.00);
$invoice->updateTotal(275.50);
$invoice->updateStatus('sent');
$invoice->updateTotal(260.00); // negotiated down
$invoice->updateStatus('paid');

echo "=== Audit Report for Invoice #5501 ===" . PHP_EOL;
printAuditReport($invoice);

// Confirms the Interface + Trait combination gives us proper type safety
var_dump($invoice instanceof Auditable); // true — Interface relationship works