Contrib.social

Require backslash prefix for global functions and constants in new code

Open on Drupal.org →
Created on 20 January 2022, over 2 years ago
Updated 13 May 2024, about 2 months ago

Problem/Motivation

This is something that I first learned thanks to the EA Extended / EA Ultimate plugin for PhpStorm.
When calling/referencing global-namespace functions or constants from within a namespace, there is some ambiguity:

namespace N;

use function strpos as strpos_alias;
use const T_STRING as T_STRING_ALIAS;

strpos(..);  // Calls \N\foo() if exists, or \foo() otherwise.
\strpos(..);  // Calls \foo();
strpos_alias(..);  // Calls \foo();

print T_STRING;  // Prints constant \N\T_STRING if exists, or \T_STRING otherwise.
print \T_STRING;  // Prints constant \T_STRING.
print T_STRING_ALIAS;  // Prints constant \T_STRING.

The non-qualified reference does have a minor performance impact, which can become relevant for repeated low-level operations.
See https://github.com/Roave/FunctionFQNReplacer for benchmarks and further reading.

In Drupal, I mostly see function calls without the clarifying leading backslash.
Outside of Drupal, I see a mix of "use function" and FQN (leading backslash) for functions, and mostly imports for constants.

I don't see a recommendation about this in our coding standards.
See https://www.drupal.org/docs/develop/standards/coding-standards#functcall →

I personally like backslash for functions and constants when writing new code - this way I don't have to keep the imports up to date, and I can easily distinguish top-namespace functions from imported namespaced functions. Plus I don't need to create aliases for namespaced constants or functions used in the same file.
For existing code, it might be less disruptive to add the imports. Although I think the auto merge resolution in PhpStorm handles the added backslash more smoothly than added imports.

State what you believe is wrong or missing from the current standards.

Benefits

If we adopted this change, the Drupal Project would benefit by having a clear policy where none exists today. Also there is a minor performance improvement.

Three supporters required

  1. https://www.drupal.org/u/kim.pepper → (2024-04-05)
  2. https://www.drupal.org/u/larowlan → (2024-04-05)
  3. https://www.drupal.org/u/catch → (2024-04-05)
  4. https://www.drupal.org/u/ → {userid} (date that user added support)

Proposed changes

Decide whether we should
- recommend or prescribe backslash.
- recommend or prescribe imports.
- recommend or prescribe to use the ambiguous reference without backslash or import.
- leave it up to the developer.

Then decide whether this should be updated in core, or just be applied to new code.

Provide all proposed changes to the Drupal Coding standards → . Give a link to each section that will be changed, and show the current text and proposed text as in the following layout:

1. {link to the documentation heading that is to change}

Add current text in blockquotes

Add proposed text in blockquotes

2. Repeat the above for each page or sub-page that needs to be changed.

Remaining tasks

  2. Add supporters
  3. Create a Change Record
  4. Review by the Coding Standards Committee
  5. Coding Standards Committee takes action as required
  6. Discussed by the Core Committer Committee, if it impacts Drupal Core
  7. Final review by Coding Standards Committee
  8. Documentation updates
    1. Edit all pages
    2. Publish change record
    3. Remove 'Needs documentation edits' tag
  9. If applicable, create follow-up issues for PHPCS rules/sniffs changes

For a full explanation of these steps see the Coding Standards project page →

📌 Task
Status

Active

Component

Coding Standards

Created by

🇩🇪Germany donquixote

Live updates comments and jobs are added and updated live.
  • Needs issue summary update

    Issue summaries save everyone time if they are kept up-to-date. See Update issue summary task instructions.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

contrib.social Blog FAQ Discussions
Production build 0.69.0 2024