====== PHP RFC: Friends ======
  * Version: 0.4
  * Date: 2026-05-04
  * Author: Daniel Scherzer, daniel.e.scherzer@gmail.com
  * Status: Under discussion
  * Implementation: https://github.com/php/php-src/pull/21937
  * Discussion thread: https://news-web.php.net/php.internals/130815

This RFC proposes adding support for friendship in PHP, allowing classes to specify other classes as friends. Those friends would then be able to access protected (but not private) properties, constants, and methods of the declaring class.

===== Introduction =====

PHP has three visibility levels

  * Public: accessible everywhere
  * Protected: accessible in the declaring class and other classes in the same hierarchy
  * Private: accessible only in the declaring class

Classes will occasionally have property or methods that need to be exposed to one or more other classes, but should not be public to everyone. These are generally internal implementation details that are exposed for use in other parts of the same library, like factory classes, but should not be used by external code.

Currently, the options to do so are limited:

  * Make things public, and document them as internal
  * Make things public, and enforce the internal-ness by examining backtraces
  * Make things protected, and have the other internal classes extend the declaring class to have access to those methods, despite not semantically making sense as subclasses
  * Don't make things public, and use reflection to access them

The use of reflection for bypassing visibility restrictions in non-test code is generally frowned upon, and should not be recommended. Using the potential combination of protected + subclasses for access, though possible, is also frowned upon as abusing the <php>protected</php> functionality. Thus, the primary approach currently taken is to make things public, and to require, via documentation, tooling, and/or runtime backtrace checks, that the internal aspect of the class is not being accessed improperly. One tool, that inspired this RFC, is the <php>#[Friend]</php> attribute from the [[https://packagist.org/packages/dave-liddament/php-language-extensions|dave-liddament/php-language-extensions]] library, which adds an attribute for friendship that is enforced via static analysis.

This RFC proposes an approach based on C++'s concept of friends. A class (e.g. <php>User</php>) can declare another class (e.g. <php>UserFactory</php>) as a friend, allowing that friend to access internal details.

After LSP issues were raised on the mailing list, the friend only has access to <php>protected</php> parts of the class, rather than also <php>private</php> parts. See the rejected features below for details.

<PHP>
<?php

class User {
    // The UserFactory class is allowed to use the protected constructor
    friend UserFactory;

    // Protected constructor - user information must come from a trusted source
    protected function __construct(
        public readonly int $userId,
        public readonly string $username,
    ) {}
}

?>
</PHP>

===== Proposal =====

Add support for PHP classes (including enums) to declare friends based on class name, following the same namespace handling rules as normal (e.g. use statements are applied). The named friend need not exist at the time of declaration, and is not autoloaded. This allows for potential friendship with external classes.

Friends (defined as classes where the fully qualified class name matches the declared friend name) are then allowed to access protected (but not private) parts of the declaring class.

For protected parts that are inherited by subclasses, when not overridden the friend can still access them. In other words, friendship checks are based on the class where a property/method/constant is defined.

To allow checking what friends a class has, a new method is added to <php>ReflectionClass</php> returning an array of the friend names:

<PHP>
<?php

class ReflectionClass implements Reflector

    // ...existing methods

    public function getFriendNames(): array {}

}

?>
</PHP>

==== Examples ====

Friends have access to protected methods (e.g. constructor):

<PHP>
<?php

class User {
    friend UserFactory;

    // Protected constructor - user information must come from a trusted source
    protected function __construct(
        public readonly int $userId,
        public readonly string $username,
    ) {}
}

class UserFactory {

    public function newFromId(int $userId): ?User {
        // In reality this would query a database or something
        return match ($userId) {
            1 => new User(1, "Alice"),
            2 => new User(2, "Bob"),
            default => null,
        };
    }
}

$factory = new UserFactory;

$alice = $factory->newFromId(1);
var_dump($alice);

$bob = $factory->newFromId(2);
var_dump($bob);

// Creation outside of the factory fails
try {
    $unknown = new User(3, "Camille");
} catch (Error $e) {
    echo $e;
}

?>
</PHP>

Friends also have access to change protected properties (including those with asymmetric visibility):

<PHP>
<?php

class User {
    friend UserBuilder;

    public protected(set) ?int $userId = null;
    public protected(set) ?string $username = null;

    // Protected constructor - use the UserBuilder
    protected function __construct() {}
}

class UserBuilder {

    public function newWithId(int $userId): User {
        $u = new User();
        $u->userId = $userId;
        return $u;
    }

    public function newWithName(string $username): User {
        $u = new User();
        $u->username = $username;
        return $u;
    }
}

$builder = new UserBuilder();

$alice = $builder->newWithId(1);
var_dump($alice);

$bob = $builder->newWithName("Bob");
var_dump($bob);

// Manipulation outside of the builder fails
try {
    $bob->userId = 2;
} catch (Error $e) {
    echo $e;
}

?>
</PHP>

==== Details ====

Assuming <php>User</php> has a friend <php>UserBuilder</php>

  * Friendship is **not mutual**. <php>UserBuilder</php> can access protected parts of <php>User</php>, but <php>User</php> cannot access the protected parts of <php>UserBuilder</php> (unless the builder also adds a friend declaration)
  * Friendship is **not transitive**. If <php>UserBuilder</php> has a friend <php>BuilderFactory</php>, that does not mean that <php>BuilderFactory</php> can access the protected parts of <php>User</php>
  * Friendship is **not inherited**. If <php>UserBuilder</php> has a subclass <php>LoggedUserFactory</php>, that subclass cannot access the protected details of <php>User</php>
    * Methods defined on <php>UserBuilder</php> that are inherited by <php>LoggedUserFactory</php> and not overridden can still access the protected details of <php>User</php>. If the method is overridden, code within that method has no extra access, but the parent method (e.g. invoked with <php>parent::</php>) still works fine.

<PHP>
<?php

// Assuming definition of User and UserBuilder classes from the example above
class LoggedUserBuilder extends UserBuilder {

    public function newWithId(int $userId): User {
        echo "Creating user with id: $userId\n";
        return parent::newWithId($userId);
    }

    public function newWithName(string $username): User {
        echo "Creating user with name: $username\n";
        return parent::newWithName($username);
    }
}

// LoggedUserBuilder doesn't actually access anything protected, that is all
// done in the parent:: calls, this works fine
$loggedBuilder = new LoggedUserBuilder();
$charlie = $loggedBuilder->newWithId(3);
var_dump($charlie);

$daniel = $loggedBuilder->newWithName("Daniel");
var_dump($daniel);

?>
</PHP>

Additionally:

  * Friendship respects asymmetric visibility - friends can modify class properties only if modifiable from the protected scope
  * Friends cannot be declared on traits or interfaces

==== Not a visibility level ====

Friendship is added orthogonally to existing visibility levels, rather than adding a new level. Friends of a class have the same level of access as a subclass would, but without the semantic implications of being a subclass.

This also presents a simple mental model - protected visibility now means "other classes in the same hierarchy, and also friends", rather than just "other classes in the same hierarchy".

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

  * The new <php>ReflectionClass::getFriendNames()</php> method means that any subclass with a method of the same name but an incompatible signature will no longer be allowed
  * New global constant <php>T_FRIEND</php> prevents userland constants of the same name when using the tokenizer extension

===== Proposed PHP Version(s) =====
Next minor version (PHP 8.6).

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

Static Analyzers will want to suppress warnings about accessing protected class members when the access is coming from a friend.

Linters and IDEs will need to update for the new syntax.

Userland PHP libraries that have internal details exposed to other parts of the library via public methods may want to migrate to using friends once they require PHP 8.6+.

==== To Existing Extensions ====
Will existing extensions be affected?

  * Opcache: caching of class entries is updated to include the list of friends of the class
  * Reflection:
    * introduction of <php>ReflectionClass::getFriendNames()</php>
    * <php>ReflectionProperty::isReadable()</php> and <php>ReflectionClass::isWritable()</php> are updated to account for friendship
  * Tokenizer: new token <php>T_FRIEND</php> for the new keyword

==== To SAPIs ====
None

===== Open Issues =====
Make sure there are no open issues when the vote starts!

===== Future Scope =====

  * Adding support for friendship allowing access to private class details
  * Adding support for inherited friendship ("UserFactory and all of its subclasses are all friends of User")
  * Adding support for namespaces as friends ("Any class in \My\Library\Namespace is a friend of User")
  * Adding support for friends on traits ("Any class that uses this trait will declare UserFactory as a friend")

===== Voting Choices =====
Please consult [[https://github.com/php/policies/blob/main/feature-proposals.rst#voting-phase|the php/policies repository]] for the current voting guidelines.

----

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

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

===== Patches and Tests =====
https://github.com/php/php-src/pull/21937

===== 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 =====
Links to external references, discussions, or RFCs.

  * Blog post with feature overview: https://scherzer.dev/Blog/20260309-php-friends
  * https://packagist.org/packages/dave-liddament/php-language-extensions
  * Pre-RFC discussion on syntax: https://externals.io/message/130710

===== Rejected Features =====
Keep this updated with features that were discussed on the mail lists.

==== Access to private class parts ====

A previous version of this RFC specified that friends have access to both protected //and private// parts of a class. However, this presents an LSP challenge. Specifically, consider code like the following:

<PHP>
<?php

class User {
    friend UserService;

    private function resetUser() {
        echo "User::resetUser()\n";
    }
}

class UserService {

    public static function resetAUser(User $u) {
        $u->resetUser();
    }
}
</PHP>

In isolation, this would work fine. However, if a subclass of the User class declared a method by the same name:

<PHP>
<?php

class OtherUser extends User {

    private function resetUser() {
        echo "OtherUser::resetUser()\n";
    }
}
</PHP>

then substituting an instance of <php>OtherUser</php> in a call to <php>UserService::resetAUser()</php> would fail, since <php>UserService</php> is not listed as a friend of <php>OtherUser</php>. The same issue occurs with properties and constants.

In the absence of a casting system to allow making it clear that the original property/method/constant on the User class is the intended target, trying to support access to private members would have required one of

  * requiring classes with friends to be final
  * preventing the shadowing of private properties/methods/constants if the parent class has friends

To avoid needing to deal with this complication, this RFC was updated to only focus on protected access, and not allow private access. Private access may be worked on in a follow-up RFC.

===== Changelog =====
If there are major changes to the initial proposal, please include a short summary with a date or a link to the mailing list announcement here, as not everyone has access to the wikis' version history.

  * v0.1: created
  * v0.2: add section explaining why friendship is not a new visibility level, improve example
  * v0.3: dropped access to private parts, only allowing protected access
  * v0.4: improved discussion of inheritance of friendship with new example