Sealed classes with PHPStan

This extension adds support for sealed classes and interfaces to PHPStan.

Installation

To use this extension, require it via Composer

composer require --dev jiripudil/phpstan-sealed-classes

If you are using phpstan/extension-installer, this extension's configuration will be automatically enabled.

Otherwise you need to include it explicitly in your phpstan.neon:

includes:
    - vendor/jiripudil/phpstan-sealed-classes/extension.neon

Usage

Sealed classes and interfaces allow developers to restrict class hierarchies: a sealed class can only be subclassed by classes that are explicitly permitted to do so. The same applies to sealed interfaces and their implementations. In a way, sealed classes are similar to enumerations, with an important distinction: while enums are singletons, a subclass of a sealed class can have multiple instances, each with its own state.

You can seal an abstract class or an interface by attributing it as #[Sealed]. The attribute accepts a list of permitted descendants or implementations:

<?php

use JiriPudil\SealedClasses\Sealed;

#[Sealed(permits: [AllowedImplementation::class, AnotherImplementation::class])]
interface SealedInterface {}

class AllowedImplementation implements SealedInterface {}
class AnotherImplementation implements SealedInterface {}
class DisallowedImplementation implements SealedInterface {}

While the first two classes will be allowed, PHPStan will report an error for the third:

------ ---------------------------------------------------------------------------------------------------
 Line   sealed-interface.php
------ ---------------------------------------------------------------------------------------------------
 10     Class DisallowedImplementation is not allowed to implement a #[Sealed] interface SealedInterface.
------ ---------------------------------------------------------------------------------------------------

Note that the restrictions do not apply to indirect subclasses. If a direct subclass of a sealed class is not sealed itself, it can be further extended without raising any errors. This code is perfectly fine:

<?php

use JiriPudil\SealedClasses\Sealed;

#[Sealed(permits: [AllowedDescendant::class])]
abstract class SealedClass {}

class AllowedDescendant extends SealedClass {}
class IndirectDescendant extends AllowedDescendant {}

Comments

Support sealing concrete classes
Currently, this extension only supports sealing abstract classes or interfaces. Is there any reason to have that restriction ?

In the upcoming v2 of scssphp, I have a use case that would require sealing a concrete class. Among our Value classes, our intent is that they should all be either final or sealed (no custom child classes are intended to be supported). But our SassList class is both a concrete class (representing normal Sass lists) and the parent of the SassArgumentList class (representing a special kind of list). Making SassList a sealed class would allow to represent that intent, but it is not supported by your package currently (disclaimer: scssphp does not use your package yet, but our other classes that would be marked as sealed are abstract so this would not be a blocker).

Supports in other languages:

Dart allows sealing concrete classes

Hack allows sealing concrete classes

Java allows sealing concrete classes

the declined PHP RFC about sealed classes was also allowing sealing concrete classes

Kotlin makes sealed classes abstract (without requiring an abstract keyword), thus forbidding sealing concrete classes
opened by stof 2