Include Constructor to be a part of CommandListInterface API, extend inline documentation

[engcom-Echo]

Description (*)

This PR is copy of 29762. As in original PR target branch was 2.5-develop we have modified to point to 2.4-develop.

In my personal opinion using CommandListInterface is invalid way of adding new Commands to interface.
It is because Constructor is not a part of Interface (Service Contract), thus it is not "guaranteed" part of Interface.

Using CommandList is against Magento rules, thus it's implementation is not guaranteed and can change in backwards-incompatible way.

I'm extending the CommandList with @api to ensure developers that this class won't change backwards-incompatible way and this way - they can either add new classes using:

• Argument injection to CommandList class
• Plugin on getCommands on CommandListInterface.

I'd love to get your feedback there.

After discussion with @kandy I decided to add the __construct() to the API.

Answering the main concerns: https://3v4l.org/8ug8i

As it affects you (community) I need your 👍🏻 or comments to pass the change:

Related Pull Requests

Fixed Issues (if relevant)

1. Fixes magento/magento2#<issue_number>

Manual testing scenarios (*)

1. ...
2. ...

Questions or comments

Contribution checklist (*)

• Pull request has a meaningful description of its purpose
• All commits are accompanied by meaningful commit messages
• All new or changed code is covered with unit/integration tests (if applicable)
• All automated tests passed successfully (all builds are green)

Thanks

• @jissereitsma for inspiration

Resolved issues:

1. resolves [Issue] Include Constructor to be a part of CommandListInterface API, extend inline documentation #31102: Include Constructor to be a part of CommandListInterface API, extend inline documentation

[m2-assistant]

Hi @engcom-Echo. Thank you for your contribution!
Here are some useful tips on how you can test your changes using Magento test environment.

Add the comment under your pull request to deploy test or vanilla Magento instance:

• @magento give me test instance - deploy test instance based on PR changes
• @magento give me 2.4-develop instance - deploy vanilla Magento instance

❗ Automated tests can be triggered manually with an appropriate comment:

• @magento run all tests - run or re-run all required tests against the PR changes
• @magento run <test-build(s)> - run or re-run specific test build(s)
  For example: @magento run Unit Tests

<test-build(s)> is a comma-separated list of build names.

Allowed build names are:

1. Database Compare
2. Functional Tests CE
3. Functional Tests EE
4. Functional Tests B2B
5. Integration Tests
6. Magento Health Index
7. Sample Data Tests CE
8. Sample Data Tests EE
9. Sample Data Tests B2B
10. Static Tests
11. Unit Tests
12. WebAPI Tests
13. Semantic Version Checker

You can find more information about the builds here
ℹ️ Run only required test builds during development. Run all test builds before sending your pull request for review.

---

For more details, review the Code Contributions documentation.
Join Magento Community Engineering Slack and ask your questions in #github channel.

[engcom-Echo]

@magento run all tests

[magento-automated-testing]

The requested builds are added to the queue. You should be able to see them here within a few minutes. Please message the #magento-devops slack channel if they don't show in a reasonable amount of time and a representative will look into any issues.

[engcom-Hotel]

This PR is the reference of the PR #29762, we have just changed the target branch to 2.4-develop from 2.5-develop.

Hence approving this PR to move forward.

Thanks

[engcom-Hotel]

Hello @lbajsarowicz,

Thanks for the contribution!

✔️ QA Passed

As in this PR, the changes are related to making the lib/internal/Magento/Framework/Console/CommandList.php class a Public Interface by adding the @api annotation and adding the return type for getCommands() as array.

There is nothing to reproduce in this issue but it is a good to have feature. Hence moving this PR further process.

Due to SVC failure, moving this PR for approval.

Thanks

[engcom-Hotel]

@magento run Functional Tests EE, Unit Tests

[magento-automated-testing]

The requested builds are added to the queue. You should be able to see them here within a few minutes. Please message the #magento-devops slack channel if they don't show in a reasonable amount of time and a representative will look into any issues.

[engcom-Hotel]

Created an approval JIRA from approval of SVC failure.

[engcom-Hotel]

@magento run Semantic Version Checker

[magento-automated-testing]

The requested builds are added to the queue. You should be able to see them here within a few minutes. Please message the #magento-devops slack channel if they don't show in a reasonable amount of time and a representative will look into any issues.

[engcom-Hotel]

@magento run all tests

[engcom-Hotel]

Hello @lbajsarowicz,

Please have a look into the below review comment. The change has been suggested by the internal team due to BiC.

Thanks

[engcom-Hotel]

Please remove this return type as this change is Backward incompatible.

[jissereitsma]

Doesn't it make sense to slowly add in type hinting like this? PHP 5.3 is quite some time ago. And you can always add stronger typing to a class without breaking the interface. As I see it, nothing is breaking backward compatibility here?

[engcom-Hotel]

Hello @jissereitsma, I guess this change breaks compatibility with existing code that:

• Calls getCommands() and expects a return type other than an array.
• Extends or implements the CommandList class or CommandListInterface without updating overridden/implemented methods.

[jissereitsma]

I'm not sure whether these arguments make sense. Yes, indeed somebody could create a DI plugin and return a string from the getCommands() method. But that will break the entire Magento CLI anyway! The same way counts for rewriting the CommandList class or CommandListInterface interface. So, the choice is between opting for the possibility that somebody has hacked the Magento core to an extend where the CLI does not work properly anymore, or sticking to modern-day PHP standards. I would opt for the future instead.

[ihor-sviziev]

Calls getCommands() and expects a return type other than an array.

It was always returning an erray, so no code can expect it

Extends or implements the CommandList class or CommandListInterface without updating overridden/implemented methods.

Technically you’re right, but if we’ll treat all changes as this - we can’t add return types to anywhere --> we’ll never have strict types

Since this class was previously not marked as API, we can still change its interface.
But after merging this PR, we can’t. So I suggest adding the return type now

[engcom-Hotel]

Hello @ihor-sviziev & @jissereitsma,

Let me discuss this with the internal team. Meanwhile moving this PR On Hold.

Thanks

[engcom-Hotel]

Hello @ihor-sviziev & @jissereitsma,

We got reply from the internal team, according to them adhering to BIC checks should remain the standard unless there is a highly compelling justification to deviate from it. In this instance, I don't find the justification sufficiently convincing.

[engcom-Dash]

@magento run all tests

[engcom-Dash]

@lbajsarowicz as per our discussion over Slack, I worked on the review comments & failed static cases. @engcom-Hotel Could you please review it?

Thanks!

[ihor-sviziev]

@engcom-Dash, we still have not resolved discussion #37901 (comment), let's agree on the final version before moving to review