Roadmap

[jrfnl]

These are preliminary roadmap notes for future PHPCSUtils versions

PHPCSUtils 1.1.0 (released)

• Add utility method to retrieve an array with stack pointers + names of all constants declared in an OO structure. - PR ✨ New ObjectDeclarations::getDeclared*() utility methods #592
• Add utility method to retrieve an array with stack pointers + names of all properties declared in an OO structure. - PR ✨ New ObjectDeclarations::getDeclared*() utility methods #592
• Add utililty method to retrieve an array with stack pointers + names of all methods declared in an OO structure. - PR ✨ New ObjectDeclarations::getDeclared*() utility methods #592
• Add utililty method to retrieve an array with stack pointers + names of all cases declared in an enum. - PR ✨ New ObjectDeclarations::getDeclared*() utility methods #592
• Add utililty method to retrieve an array with stack pointers + names of all functions declared in a file in the current namespace (outside OO). (see Trackers)
• Add utility class Constants for working with (OO) constant declarations. - PR ✨ New PHPCSUtils\Utils\Constants class + associated token collection #562
  Initial list of methods:
  • getMemberProperties(File $phpcsFile, int $stackPtr): array to retrieve the modifier information for an OO constant declaration, i.e. returns an array with is_final, final_token, visibility, visibility_token keys (can be false if visibility is not explicitly specified).
• Add utility class TypeString for working with type declaration strings. - ✨ New TypeString utility class #588
  Preliminary list of methods:
  • isSingularType(string $typeString): bool
  • isComplexType(string $typeString): bool
  • isUnionType(string $typeString): bool
  • isIntersectionType(string $typeString): bool
  • isDNFType(string $typeString): bool (PHP 8.2+ disjunctive normal form)
  • getTypes(string $typeString): array to split a type string into its individual parts
    (Note to self: mind whitespace (and comments) within types! - Confirmed that BCFile, FunctionDeclarations and Variables methods return a type string without comments and whitespace)
  • getOOTypes(string $typeString): array to get only the OO names from a type string

PHPCSUtils 1.2.0 (released)

• Add various utilities around PHP attributes. - ✨ New *::getAttributeOpeners() methods #719, ✨ New PHPCSUtils\Utils\AttributeBlock class #720, ✨ New PHPCSUtils\Utils\AttributeBlock::appliesTo() method  #729

PHPCSUtils 1.3.0 (or later)

• Add isUseOfGlobalConstant() method to determine whether an arbitrary name token (in PHPCS 3.x always T_STRING) is the use of a "global" constant, with the caveats that unless the constant is declared in the current file or imported via a use const statement, the method will not be able to distinguish between a global and a namespaced token when the constant is declared in the current namespace.
• Add utililty class for resolving inline names to fully qualified names.
• Add a number of "tracker" classes which keep track of certain information seen in a file, like seen namespaces, current namespace, seen use statements etc
  • NamespaceTracker
  • ImportUseTracker
  • DeclaredFunctionsTracker (non-OO)
• Add abstract sniff classes for a couple of frequently occurring situations, like:
  • Detecting all places a certain class name is used (extends, new, instanceof, catch, use statements, type declarations etc).
  • Detecting all places a certain interface name is used (extends (for interface declarations), implements, instanceof, use statements, type declarations etc).
  • Detecting all places a certain function name is used (function calls, use function statements, maybe callbacks).
  • Detecting all places a certain constant name is used (constant use, use const statements).
  • Examining the parameters of function calls to a limited list of functions.

PHPCSUtils 1.4.0 (or later)

• Add utililty class to find the docblock for a construct, supporting all typical constructs which take docblocks (file, OO, function, constant, property, enum case, etc)
• Add utililty class to work with docblock tags and their descriptions
• Add utility class to work with inline comments

Future scope (version to be determined)

• Improved version of the PHPCS native AbstractScopeSniff, i.e. more akin to AbstractDirectScope to allow for sniffs to run certain code for tokens in the global scope and other code for tokens in an OO/function scope.
• Add abstract base test class for use by external standards:
  • Fully compatible with the functionality in the PHPCS native PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest.
  • Allow for running sniff class tests on PHPUnit 4.x - 9.x.
  • Allow for verifying that the correct error code(s) are being shown on each line expecting errors/warnings.
  • Allow for testing the error/warning messages.
  • Allow for testing the metrics.
  • Runs with a clean Config for each test class to prevent configuration directives set for one sniff influencing the tests for another.
• NamingConventions: a set of methods to verify a "label name" (class, function etc) complies with certain naming conventions and methods to convert a label to a certain convention
• Add abstract sniff class to examine callbacks
• Add helper method to parse an enum declaration statement ?
• Add TypeString::isValid(string $typeString): bool to verify that a type string is valid ?
  This could potentially check for things like:
  - Duplicate names/types in the type string
  - Nullability operator ? being used with complex types (should use |null)
  - Invalid types like resource being used ?

[jrfnl]

While most things in this roadmap are still planned for the foreseeable future, the order of when things will become available and in what release is likely to change with an eye on PHPCS 4.0 coming out sooner rather than later and the possibility that PHPCSUtils will at some point in the future become a runtime dependency for PHPCS itself.

Features which will make the transition to PHPCSUtils for external standards easier will get higher priority than other new features.

[andrewnicols]

Hi @jrfnl,

We (Moodle) have been doing some work with docblocks which may help towards the docblock goal.
It is not yet complete, and we're still tweaking things, but it may be a starting point for the docblock work: https://github.com/moodlehq/moodle-cs/blob/main/moodle/Util/Docblocks.php

At the moment it handles file docblocks, and ooScopes docblocks.
I'm getting ready to land a couple of commits to simplify and normalise it:

• it currently returns the token array rather than the pointer
• I want it to be stricter about the requested stackPtr so that it can support other constructs more easily
• need to move some unit tests around

Let me know if this might be of use and I can see how we can help further.

[jrfnl]

@andrewnicols I've got a couple of (unfinished) branches locally and would love to chat about this at some point. Got some different priorities first now, but I'd be happy to discuss this in a call once things quieten down a little. Would you be up for that ?

[andrewnicols]

@jrfnl definitely up for that (cc @stronk7)

[jrfnl]

@andrewnicols Let me try and get PHPCS 4.0 out of the door first over the next few months. Once that's out, this is one of the next things on my list. (and plenty more, but I'll tell you about that if you're interested in that call ;-) )

[andrewnicols]

Another question for you @jrfnl, I see you have on the roadmap to " Add utililty class for resolving inline names to fully qualified names." .

I assume that means to take a class name, with or without a leading \, and resolve it based on information within that class (namespace and class imports) to make it fully qualified.

Did you have any thoughts on how you would like that to look and work?

Equally I don't see anything here relating to Attributes - do you have any plans, thoughts, etc. on an Attribute Util?

[jrfnl]

@andrewnicols I have a feeling it might be easier to give you some more insight into what I'm currently working on via a videocall. You previously indicated that you'd be interested in that, so let's get one set up. Is there a time today/tomorrow which would work for you ?
If you prefer, you can DM me on Twitter/Mastodon to set it up. /cc @stronk7

[jrfnl]

FYI: I've just updated the roadmap a little.

I intend to release v 1.0.12 soon after PHPCS 3.10.0 has been released. That version will add support for PHP 8.2 DNF types in all the relevant places.

While what I originally intended to include in the PHPCS 1.1.0 milestone isn't completely finished yet, I don't want to hold back what is ready any longer, so I intend to merge what's ready soon after the 1.0.12 release and to release version 1.1.0 a week or two later.

I have made steady progress on the other features (name resolution for inline names, Trackers, abstracts), but am not fully satisfied with their design yet. I intend to get back to these over the summer and hope to be able to release PHPCSUtils 1.2.0 with these features towards the end of the summer. Once those features are available, the PHPCS 4.0 release should follow soon after.