Contrib.social

Allow type hinting with classes where appropriate

Open on Drupal.org →
Created on 10 February 2022, about 3 years ago
Updated 17 July 2024, 9 months ago

Problem/Motivation

There are cases where we use value objects, or where providing an interface for an otherwise one-off class will do more harm than good.

Benefits

If we adopted this change, the Drupal Project would benefit by ...

Three supporters required

  1. https://www.drupal.org/u/ → {userid} (yyyy-mm-dd they added support)
  2. https://www.drupal.org/u/ → {userid} (yyyy-mm-dd they added support)
  3. https://www.drupal.org/u/ → {userid} (yyyy-mm-dd they added support)

Proposed changes

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. https://www.drupal.org/docs/develop/standards/coding-standards#s-objects →

Use an interface typehint for parameter and return types (not a class). Typehint the most specific interface that encompasses all possible parameter or return values. Do not use stdClass.

Use an interface typehint for parameter and return types where available. Typehint the most specific interface or class that encompasses all possible parameter or return values.

2. https://www.drupal.org/docs/develop/standards/php/object-oriented-code#i... →

Use of interfaces

The use of a separate interface definition from an implementing class is strongly encouraged because it allows more flexibility in extending code later. A separate interface definition also neatly centralizes documentation making it easier to read. All interfaces should be fully documented according to established documentation standards.

If there is even a remote possibility of a class being swapped out for another implementation at some point in the future, split the method definitions off into a formal Interface. A class that is intended to be extended must always provide an Interface that other classes can implement rather than forcing them to extend the base class.

None. The text is to be deleted.

3. https://www.drupal.org/docs/develop/standards/php/object-oriented-code#h... →

Type hinting

PHP supports optional type specification for function and method parameters for classes and arrays. Although called "type hinting" it does make a type required, as passing an object that does not conform to that type will result in a fatal error.

  • DO specify a type when conformity to a specific interface is an assumption made by the function or method. Specifying the required interface makes debugging easier as passing in a bad value will give a more useful error message.
  • DO NOT use a class as the type in type hinting. If specifying a type, always specify an Interface. That allows other developers to provide their own implementations if necessary without modifying existing code.

Example:

// Correct:
function make_cat_speak(FelineInterface $cat) {
  print $cat->meow();
}

// Wrong:
function make_cat_speak(GarfieldTheCat $cat) {
  print $cat->meow();
}

None. The text is to be deleted.

Remaining tasks

\
Needs examples.

  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 →

Possible follow up to remove to remove https://www.drupal.org/docs/develop/standards/object-oriented-code → .

📌 Task
Status

Active

Component

Coding Standards

Created by

🇬🇧United Kingdom catch

Live updates comments and jobs are added and updated live.
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.71.5 2024