Table of Contents

PHP RFC: #[\NonExhaustive] marker

This is the suggested template for PHP Request for Comments (RFCs). Change this template to suit your RFC. Not all RFCs need all the sections below.

Please read https://wiki.php.net/rfc/howto carefully!

Quoting Rasmus:

PHP is and should remain:
1) a pragmatic web-focused language
2) a loosely typed language
3) a language which caters to the skill-levels and platforms of a wide range of users

Your RFC should move PHP forward following his vision. As said by Zeev Suraski “Consider only features which have significant traction to a large chunk of our userbase, and not something that could be useful in some extremely specialized edge cases [...] Make sure you think about the full context, the huge audience out there, the consequences of making the learning curve steeper with every new feature, and the scope of the goodness that those new features bring.”

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
 
echo "Showcase your idea here";
 
?>

Proposal

Add the following attribute to Zend/zend_attributes.stub.php (in the global namespace): 

/* The attribute targets are further restricted to classes of type enum. *>/
#[\Attribute(Attribute::TARGET_CLASS)]
final class NonExhaustive
{
    public function __construct() {}
}

The purpose of this attribute is to indicate that an enum might get additional cases in a future version. Code that consumes the enum in question must be prepared to gracefully handle unknown cases, for example by including a default arm within the match() expression.

Examples

<?php
 
enum FileError {
    case NotFound;
    case PermissionDenied;
}
 
function getHumanMessage(FileError $error): string {
    return match ($error) {
        FileError::NotFound => "The file could not be found",
        FileError::PermissionDenied => "Insufficient permissions to access the file",
 
        // Gracefully handle new error situations, e.g. "IsDirectory".
        default => "Failed to interact with the file",
    };
}
 
?>

Backward Incompatible Changes

What breaks, and what is the justification for it?

Please include all breaking changes, no matter how minor they might appear. All research you did on potential impact should be listed in this section.

For adding new functions, classes or keywords, here are some possibilities to measure potential impact:

Proposed PHP Version(s)

Next PHP 8.6.

RFC Impact

To the Ecosystem

What effect will the RFC have on IDEs, Language Servers (LSPs), Static Analyzers, Auto-Formatters, Linters and commonly used userland PHP libraries?

To Existing Extensions

Extensions should apply the attribute to enums as appropriate.

To SAPIs

None.

Open Issues

None.

Future Scope

The attribute might be applicable to further constructs in future PHP versions.

Voting Choices

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

Implement the #[\NonExhaustive] attribute as outlined in the RFC?
Real name Yes No Abstain
Final result: 0 0 0
This poll has been closed.

Patches and Tests

Links to proof of concept PR.

If there is no patch, make it clear who will create a patch, or whether a volunteer to help with implementation is needed.

Implementation

After the RFC is implemented, this section should contain:

  1. the version(s) it was merged into
  2. a link to the git commit(s)
  3. a link to the PHP manual entry for the feature

References

Links to external references, discussions, or RFCs.

Rejected Features

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

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.