====== PHP RFC: Explicit $this parameter ======
  * Version: 1.0
  * Date: 2026-02-08
  * Author: Tim Düsterhus (tim@tideways-gmbh.com), Arnaud Le Blanc (arnaud.lb@gmail.com)
  * Status: Draft
  * Implementation: tbd

===== Introduction =====
The elevator pitch for the RFC. The first paragraph of this section will be rendered slightly larger to give it emphasis.

Please write an introduction that helps people by providing concise context and include a representative small code snippet.

<PHP>
<?php
 
$dates = [
    new DateTimeImmutable('now'),
];
 
$formattedDates = array_map(DateTimeImmutable::format(this: ?, "c"), $dates);
 
echo implode(", ", $formattedDates), PHP_EOL; // 2026-02-08T19:00:00+00:00

?>
</PHP>

===== Proposal =====

We propose allowing a named parameter <php>this:</php> to be combined with the “scope resolution operator” syntax of referring to a method to be used as an alternative way of calling an instance method. The value passed to the <php>this:</php> parameter will effectively be used as the left side of the <php>-></php> operator:

Since the <php>this:</php> parameter does not refer to a parameter in the underlying argument list and thus there is no ambiguity with regard to positional parameters it may be placed at any position of the parameter list. In particular it may appear at the first position, before all positional parameters, mirroring the left-most position for a regular method call.

<PHP>
$now = new DateTimeImmutable();

$formatted = DateTimeImmutable::format(this: $now, "c");
// is effectively equivalent to
$formatted = $now->format('c');
</PHP>

==== Liskov Substitution Principle ====

The semantics follow that of a “wrapper function” copying all parameter names, parameter types and the return type of the method specified in the method reference. The parameter type of the <php>this:</php> parameter is the class name that is specified in the method reference. If the method is overridden in a child class, the overridden method will be called, not the method that is specified.

This also means that it is legal to specify an interface method and provide any object implementing the interface.

<PHP>
$formatted = DateTimeInterface::format(this: new DateTimeImmutable(), "c");
</PHP>

Since the semantics follow that of a “wrapper function”, the signature does not adapt to the object that is actually passed. If a parameter is widened in a child class only the original types remain valid. If a parameter is renamed, the parameter name of the specified method must be used.

<PHP>
interface MyInterface {
    public function method(string $foo): int|string|bool;
}
 
class ParentClass implements MyInterface {
    public function method(string|array $foo): string {
        return 'parent';
    }
}
 
class ChildClass extends ParentClass {
    public function method(string|array $bar): string {
        return 'child';
    }
}

// Throws TypeError, since an array is not a valid parameter on the interface,
// despite being valid on ChildClass::method().
MyInterface::method(this: new ChildClass(), []); 
 
// Throws an Error about an unknown parameter 'bar', because the parameter
// is called 'foo' on ParentClass::method().
ParentClass::method(this: new ChildClass(), bar: []);

// Calls ChildClass::method().
var_dump(ParentClass::method(this: new ChildClass(), foo: 'bar')); // string(5) "child"
</PHP>

It is however not allowed to provide an object that is not contravariant with the specified class name, even if it implements a method with a compatible signature: 

<PHP>
final class NotDateTimeImmutable {
    public function format(string $format): string { }
}

// Throws a TypeError.
$formatted = DateTimeImmutable::format(this: new NotDateTimeImmutable(), "c");
</PHP>

=== Default Values ===

Default values are taken from the method that is actually being executed, not the method that is specified in the method reference. There are two reasons for these semantics:

  - The “child method” could define additional parameters where no default value is available within the “parent method”.
  - Consistency with the semantics of partial function application.

<PHP>
class ParentClass {
    public function dump(string $x = 'ParentClass') {
        var_dump($x);
    }
}
class ChildClass extends ParentClass {
    public function dump(string $x = 'ChildClass', string $y = 'extra parameter') {
        parent::dump($x);
        var_dump($y);
    }
}

ParentClass::dump(this: new ChildClass());
// string(10) "ChildClass"
// string(15) "extra parameter"
</PHP>

=== From Within The Class ===

There is one exception from the rule that the child class' method will be called if it is overridden. For a call <php>ClassName::method(this: $object)</php> if:

  - The referenced class name <php>ClassName</php> matches that of a parent (or grandparent, grandgrandparent, …) class of the current class (<php>is_subclass_of(self::class, ClassName::class)</php>).
  - The object <php>$object</php> is an instance of the current class (<php>$object instanceof self</php>).

The <php>method()</php> defined in <php>ClassName</php> will be called, not <php>$object->method()</php>.

<PHP>
class GrandparentClass {
    public function method() {
        echo "Grandparent";
    }
}

class ParentClass extends GrandparentClass {
    public function method() {
        echo "Parent";
    }
}

class Example extends ParentClass {
    public function method() {
        echo "Example";
    }
    
    public function sameClass() {
        // Existing behavior: Echos "Grandparent".
        GrandparentClass::method();
        
        // this: parameter with $this as value. Also echos "Grandparent",
        // mirroring the existing behavior, but making it clear that
        // GrandparentClass::method() is not a static method call by
        // explicitly providing $this.
        GrandparentClass::method(this: $this);
        
        // The same happens when specifying a different object instance
        // of MyClass. This also echos "Grandparent".
        GrandparentClass::method(this: new MyClass());
    }
    
    public function childClass() {
        // Existing behavior: Echos "Grandparent".
        (new ChildClass())->bypassOverridden();
        
        // this: parameter with an instance of ChildClass as value.
        // Also echos "Grandparent", mirroring the existing capabilities.
        GrandparentClass::method(this: new ChildClass());
    }
    
    private function bypassOverridden() {
        GrandparentClass::method();
    }
    
    public function parentClass() {
        // It however does not happen when specifying an object instance
        // of a parent class.
        // This echos "Parent".
        GrandparentClass::method(this: new ParentClass());
    }
}

class ChildClass extends Example {
    public function method() {
        echo "Child";
    }
}
</PHP>

==== Dynamic Parameter Lists ====

For the <php>this:</php> parameter to be recognized it needs to be explicitly specified. Dynamically passing it using argument-unpacking of an <php>array</php> or <php>Traversable</php> with a key <php>'this'</php> will not result in an instance call. The same applies for dynamic calls using <php>call_user_func()</php> and <php>call_user_func_array()</php>. There are two reasons for this:

  - The decision between an instance call or a static call should not be made at runtime.
  - Enabling a <php>'this'</php> parameter name to be passed into a variadic parameter.

<PHP>
final class Example {
    public function instanceCall(...$args) {
        var_dump($args);
    }
    
    public static function staticCall(...$args) {
        var_dump($args);    
    }
}

Example::instanceCall(this: new Example(), ...['this' => 'this', 'foo' => 'bar']);
// array(2) {
//   ["this"]=>
//   string(4) "this"
//   ["foo"]=>
//   string(3) "bar"
// }
Example::staticCall(...['this' => new Example(), 'foo' => 'bar']);
// array(2) {
//   ["this"]=>
//   object(Example)#1 (0) {
//   }
//   ["foo"]=>
//   string(3) "bar"
// }

call_user_func_array(['Example', 'staticCall'], ['this' => new Example(), 'foo' => 'bar']);
// array(2) {
//   ["this"]=>
//   object(Example)#1 (0) {
//   }
//   ["foo"]=>
//   string(3) "bar"
// }
</PHP>

==== __call() ====

Virtual methods using <php>__call()</php> are supported as expected.

<PHP>
final class Example {
    public function __call(string $name, array $arguments) {
        var_dump($name);
    }
}

Example::magic(this: new Example()); // string(5) "magic"
</PHP>

==== Static Methods and Free-standing Functions ====

Free-standing functions however may not be called with <php>this:</php>.

<PHP>
function example() { }

example(this: new stdClass()); // Not allowed.
</PHP>

Although not particularly useful, static methods are supported, similarly to how it is legal to call static methods using the <php>-></php> operator. The <php>static::class</php> value matches the class of the passed object:

<PHP>
class ParentClass {
    public static function staticMethod() {
        var_dump(static::class);
    }
}

class ChildClass extends ParentClass { }

ParentClass::staticMethod(this: new ChildClass()); // string(10) "ChildClass"
</PHP>

It remains illegal to define a parameter called <php>$this</php>:

<PHP>
final class Example {
    public static function staticMethod(
        $this, // Not allowed.
    ) { }
}
</PHP>

==== Partial Function Application ====

The <php>this:</php> parameter may be combined with partial function application to create a partial function where the “object instance” will be filled in at call time. Specifying the <php>this:</php> parameter outside the left-most position is particularly useful for partial function application, since it allows to specify the position of the object instance parameter relative to regular parameters. If a variadic placeholder is specified it must come last.

<PHP>
$c = DateTimeImmutable::format(this: ?, "c");
$c = DateTimeImmutable::format(this: ?, format: "c");
// are both effectively equivalent to:
$c = static fn (DateTimeImmutable $__this): string
    => $__this->format('c');
</PHP>

<PHP>
$c = DateTimeImmutable::setTimestamp(this: ?, ?);
$c = DateTimeImmutable::setTimestamp(this: ?, timestamp: ?);
// are both effectively equivalent to:
$c = static fn (DateTimeImmutable $__this, int $timestamp): DateTimeImmutable
    => $__this->setTimestamp($timestamp);

// and

$c = DateTimeImmutable::setTimestamp(this: ?, ...);
// is effectively equivalent to:
$c = static fn (DateTimeImmutable $__this, int $timestamp): DateTimeImmutable
    => $__this->setTimestamp($timestamp, ...array_slice(func_get_args(), 2));

// but
 
$c = DateTimeImmutable::setTimestamp(?, this: ?);
$c = DateTimeImmutable::setTimestamp(timestamp: ?, this: ?);
// are both effectively equivalent to:
$c = static fn (int $timestamp, DateTimeImmutable $__this): DateTimeImmutable
    => $__this->setTimestamp($timestamp);
</PHP>

If the this: parameter is placed after optional parameters, they will become required.

<PHP>
$c = DateTimeImmutable::setTime(this: ?, ?, ?, ?, ?);
// is effectively equivalent to:
$c = static fn (DateTimeImmutable $__this, int $hour, int $minute, int $second = 0, int $microsecond = 0): DateTimeImmutable
    => $__this->setTime($hour, $minute, $second, $microsecond);
 
// but
 
$c = DateTimeImmutable::setTime(?, ?, ?, ?, this: ?);
// is effectively equivalent to:
$c = static fn (int $hour, int $minute, int $second, int $microsecond, DateTimeImmutable $__this): DateTimeImmutable
    => $__this->setTime($hour, $minute, $second, $microsecond);
</PHP>

=== From Within The Class ===

The method lookup rules for direct calls apply equally to partial function application. The <php>self</php> at the time of the PFA declaration is relevant.

<PHP>
class GrandparentClass {
    public function method() {
        return "Grandparent";
    }
}

class ParentClass extends GrandparentClass {
    public function method() {
        return "Parent";
    }
}

class Example extends ParentClass {
    public function method() {
        return "Example";
    }
    
    public static function run($objects) {
        return array_map(GrandparentClass::method(this: ?), $objects);
    }
    
    public static function runWithPfa($pfa, $objects) {
        return array_map($pfa, $objects);
    }
    
    public static function getPfa() {
        return GrandparentClass::method(this: ?);
    }
}

class ChildClass extends Example {
    public function method() {
        return "Child";
    }
}

$objects = [
    new GrandparentClass(),
    new ParentClass(),
    new Example(),
    new ChildClass(),
];

// PFA is defined and called within Example.
// Echos "Grandparent, Parent, Grandparent, Grandparent"
echo implode(", ", Example::run($objects));

// PFA is defined within Example and called within the global scope.
// Echos "Grandparent, Parent, Grandparent, Grandparent"
echo implode(", ", array_map(Example::getPfa(), $objects));

// PFA is defined and called within the global scope.
// Echos "Grandparent, Parent, Example, Child"
echo implode(", ", array_map(GrandparentClass::method(this: ?), $objects));

// PFA is defined within the global scope and called within Example
// Echos "Grandparent, Parent, Example, Child"
echo implode(", ", Example::runWithPfa(GrandparentClass::method(this: ?), $objects));
</PHP>

==== Examples ====

There are two main use cases. The primary use case is enabling partial function application for the object instance:

<PHP>
<?php
 
$dates = [
    new DateTimeImmutable('now'),
];
 
$formattedDates = array_map(DateTimeImmutable::format(this: ?, "c"), $dates);
 
echo implode(", ", $formattedDates), PHP_EOL; // 2026-02-08T19:00:00+00:00
</PHP>

<PHP>
// Partially applying $this for the 'choice_label' with Symfony Form’s ChoiceType 
// https://symfony.com/doc/current/reference/forms/types/choice.html#advanced-example-with-objects

$builder->add('category', ChoiceType::class, [
    'placeholder' => false,
    'choices' => [
        new Category('Cat1'),
        new Category('Cat2'),
        new Category('Cat3'),
        new Category('Cat4'),
    ],
    'choice_label' => Category::getName(this: ?),
    /* … */
]);
</PHP>

The other is making calls to grandparent methods explicit:

<PHP>
<?php

class GrandparentClass {
    public function method() {
        echo "Grandparent";
    }
}

class ParentClass extends GrandparentClass {
    public function method() {
        echo "Parent";
    }
}

class Example extends ParentClass {
    public function method() {
        // Call instance method on grandparent.
        GrandparentClass::method(this: $this);
    }
}
</PHP>

===== Backward Incompatible Changes =====

While <php>$this</php> is a reserved variable name, thus is guaranteed to never be a valid parameter name, it may nevertheless be used as a named parameter name to use as a key for a variadic parameter:

<PHP>
<?php

function dump(...$args) {
    var_dump($args);
}

dump(this: 'this'); // array(1) { ["this"]=> string(4) "this" }
</PHP>

If this RFC is accepted, this would fail with a clear compile-time error for non-methods. For methods it will fail at runtime, unless the value passed to <php>this:</php> happens to be of the correct type. Users are still able to use <php>"this"</php> as a key in the resulting array by using the array unpacking syntax to pass parameters:

<PHP>
dump(...['this' => 'test']);
</PHP>

Seifeddine Gmati scanned 18975 Packagist packages containing 626044 files with Mago without finding any usage of <php>this:</php> as a named parameter. For reference, <php>self:</php> also had zero usages, <php>object:</php> had 32 and <php>static:</php> had 6.

Given that the backwards compatibility break has a direct workaround that does not require complex tooling combined with the non-existent usage in public libraries, we expect the impact to be minimal in practice.

===== Proposed PHP Version(s) =====

Next PHP 8.x (8.6).

===== RFC Impact =====
==== To the Ecosystem ====

IDEs and Static Analyzers need to understand the special semantics of the <php>this:</php> parameter to provide proper diagnostics:

  * It does not refer to an actual parameter, but to the <php>$this</php> value in an instance call
  * It may appear before positional parameters, despite being a named parameter.

It does now introduce any new syntax, thus files making use of the feature continue to parse correctly and incorrect diagnostics are localized to the calls making use of the feature.

==== To Existing Extensions ====
None.

==== To SAPIs ====
None.

===== Open Issues =====
None.

===== Future Scope =====
This section should outline areas that you are not planning to work on in the scope of this RFC, but that might be iterated upon in the future by yourself or another contributor.

This helps with long-term planning and ensuring this RFC does not prevent future work.

===== Voting Choices =====

Primary Vote requiring a 2/3 majority to accept the RFC:

<doodle title="Implement an explicit $this parameter as outlined in the RFC?" voteType="single" closed="true" closeon="2026-01-01T15:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

===== Patches and Tests =====

tbd

===== Implementation =====
After the RFC is implemented, this section should contain:
  - the version(s) it was merged into
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====

  * [[partial_function_application_this|Partial Function Application for instance of non-static methods ("$this")]]: A precursor RFC to this one.

===== Rejected Features =====

None.

===== Changelog =====

  * 2026-02-16: Initial version