DEV Community

Orfeo
Orfeo

Posted on

Using @mixin for referencing in traits in PHP (Laravel example)

#tutorial #laravel #tooling #php

When building modular PHP applications, traits are a great way to keep your code organized and reusable. Let’s walk through an example showing how to make your editor and static analysis tools fully understand the connection between a trait and a model.

Step 1: The problem

Let’s say you have a Document model with a toPdf() method. To make your model more maintainable, you extract the PDF generation logic into a trait called DocumentPdfTrait.

But when working in VS Code with PHP Intelephense, you notice that inside the trait, the editor doesn’t recognize the model’s properties or methods:

trait DocumentPdfTrait
{
    public function toPdf(): string
    {
        // $this->title belongs to Document model
        $title= $this->title; // IDE: “Undefined property: title”
        $body = $this->getBody(); // No autocomplete or navigation
        return PdfGenerator::generateToTmpPath($title, $body);
    }
}
Enter fullscreen mode Exit fullscreen mode

You lose autocompletion, “Go to definition,” and type checking—all crucial for avoiding errors in large projects.

Step 2: The solution — using @mixin

To fix this, add a DocBlock with the @mixin annotation above your trait. This tells your IDE and static analyzers that the trait behaves as if it’s part of the Document model.

/**
 * @mixin \App\Models\Document
 */
trait DocumentPdfTrait
{
    public function toPdf(): string
    {
        $title = $this->title;
        $body = $this->getBody()
        return PdfGenerator::generateToTmpPath($title, $body);
    }
}
Enter fullscreen mode Exit fullscreen mode

Step 3: The result in your editor

Once you add this line:

  • Autocomplete recognizes all model attributes and methods.
  • Function navigation (Go to Definition) starts working again.
  • Error detection improves—for example, calling an undefined method will trigger a warning.

Your editor now treats the trait’s code as though it were written inside the Document class itself.

Step 4: Static analysis tools (PHPStan, Psalm)

The @mixin annotation isn’t just helpful for IDEs—it also improves static analysis results in tools like PHPStan and Psalm.

Without @mixin, these tools may report “undefined property” or “undefined method” errors inside your trait. After adding the annotation:

  • PHPStan and Psalm correctly infer the available methods and attributes from the Document model.
  • False positives are greatly reduced, especially in complex Laravel projects.
  • You maintain strict type safety while keeping your code modular.

If you’re running PHPStan, for example, running:

vendor/bin/phpstan analyse
Enter fullscreen mode Exit fullscreen mode

will now pass cleanly for your trait without any “undefined” warnings.

This makes @mixin a small but powerful tool for ensuring that your codebase stays clean, navigable, and statically analyzable—even when splitting functionality across multiple traits.

Top comments (0)