Create class to replace hook_requirements('install')

That was considered, I'll update the meta to add more details, but here is the gist.

We replace the $phase = 'install' portion with this issue.

We replace the $phase = 'update' with #3490842: Create hook_update_requirements() and hook_update_requirements_alter()

And we replace the $phase = 'runtime' with #3490841: Create hook_runtime_requirements() and hook_runtime_requirements_alter()

Once we have all three this covers most cases, but for more complex hook_requirements like system and package_manager with multiple phases we convert in a follow up.

Once core is converted we deprecate hook_requirements being called without LegacyHook being attached.

We can document it on the interface, which is where I put it, if you think it needs more feel free to suggest more documentation. If you want to standardize how that documentation is handled that would likely be best handled in a separate issue I'd be happy to look at, but it should not block this issue.

/**
   * Check installation requirements.
   *
   * Classes implementing this must be in the Install namespace.
   * For example src/Install/ModuleNameRequirements.php.
   * Classes implementing this must be a camel case version of the project
   * name and end in Requirements.
   * There must be only one class implementing this per project.
   *
   * During the 'install' phase, modules can for example assert that
   * library or server versions are available or sufficient.
   * Note that the installation of a module can happen during installation of
   * Drupal itself (by install.php) with an installation profile or later by hand.
   * As a consequence, install-time requirements must be checked without access
   * to the full Drupal API, because it is not available during install.php.
   * If a requirement has a severity of REQUIREMENT_ERROR, install.php will abort
   * or at least the module will not install.
   * Other severity levels have no effect on the installation.
   * Module dependencies do not belong to these installation requirements,
   * but should be defined in the module's .info.yml file.
   *
   * During installation, if you need to load a class from your module,
   * you'll need to include the class file directly.
   *
   * @return array
   *   An associative array where the keys are arbitrary but must be unique (it
   *   is suggested to use the module short name as a prefix) and the values are
   *   themselves associative arrays with the following elements:
   *   - title: The name of the requirement.
   *   - value: This should only be used for version numbers, do not set it if
   *     not applicable.
   *   - description: The description of the requirement/status.
   *   - severity: (optional) The requirement's result/severity level, one of:
   *     - REQUIREMENT_INFO: For info only.
   *     - REQUIREMENT_OK: The requirement is satisfied.
   *     - REQUIREMENT_WARNING: The requirement failed with a warning.
   *     - REQUIREMENT_ERROR: The requirement failed with an error.
   *     Defaults to REQUIREMENT_OK when installing.
   */

If you mean the implementation side then we can just document the classes implementing it.

I still think 18 is a separate issue and not a blocker. For 19 there are two reasons:

1. The other two are invoked by module handler so we can just change the hook, I made it two so it's cleaner.
2. This one happens during Drupal or module install it's too early for discovery to work to check. It works now because the installer loads the install file and calls a magically named function.

We're essentially doing the same thing here, we don't get the full benefits of OOP loading etc, but we get the following benefits.

1. We can only replace hook_requirements if we replace all three parts.
2. Magically named procedural functions are really outdated.
3. It's better organized and won't be mixed in with update or install or schema.

This is ready to review again, the concerns on the meta have been resolved.

I'm happy to work on wording in a sibling issue if you create it, I think it would belong in a subpage here: https://www.drupal.org/docs/getting-started/system-requirements

Those are good ideas I can update this later.

I still think we should do this for the reasons stated in in the meta, particularly it's easier for people to know each has a phase somewhere to go. We can mention in the CR that it is preferred to use composer and a link to the issue to watch, and that this is intended as a bridge.

Ok I addressed all of your feedback I agree it looks cleaner.

I did originally copy the class load from the drupal_check_profile, is that a separate concern?

Setting it back to needs review because I addressed the feedback and it's green.

I'm going to update my comment on the meta.

As a counterpoint, I think it is far more standard to look at the interface something is extending and have the documentation there.

That documentation tells you that it must be magically named.

The implements piece is something the community is used to but you either have to leave the ide to find docs or you have to know to search for function hook_requirements otherwise search results are flooded with other implementations.

Also implements comments can be wrong or missing, extend can't be.

Again finding other implementations of a hook either requires leaving your ide, knowing regex, or the implementors perfectly following the naming scheme for a comment.

Finding classes implementing an interface is mostly built in to ides and something people beyond the community are used to too.

I agree having docs outside the ide is helpful which is why I suggested that docs pages, other suggestions are welcome.

If you're looking for a way to document classes implementing an interface the issue smustgrave created is probably the place to discuss that process and what is needed. It should probably be moved to api and retitled to focus on this use case since we already have one for hooks specifically.

@alexpott, I addressed your feedback and created the followup here: #3498992: Remove class_loader in drupal_check_profile.

On the class name: Do we really need to prefix it with a camel-cased moduel name? Yes, we do it for ServiceProvider, but it's namespaced anyway. Yes, we'd have 5,10, ... "InstallRequirements" classes, but is that really a problem?

Yes, we cannot autoload it so there is no way to find it without knowing the naming convention unless you have a different idea.

I think prefixing keeps it closer to the service provider model and makes it easier to find the one you want.

Yes removing them is the long term goal, but finding a specific install requirements in a list of 15 will be extremely painful.

I'll fix it, the test names are wrong.

I agreed with most of your comments, I had to resolve most of them so I could set up my own suggestion though, e.g. I renamed module to extension.

I honestly think naming them all the same would be a huge DX problem.

As for the requirements constants, I think we address that in the follow up to handle those oddities.

I wonder if this will work #2910814: Deprecate magic ServiceProvider file discovery

Yeah, I think we need him to weigh in.

#2910814: Deprecate magic ServiceProvider file discovery won't work for this situation cause we need it for modules that are not yet installed.

What if we do a small discovery in the install namespace, then it can be named whatever as long as it extends the requirements class.

Ok, how about MR !11218 as an approach?

Now the only restrictions are that it be in the Install namespace and that it subclass InstallRequirementsInterface

I think that is acceptable and there is no magic naming whatsoever so we can name it unique so it can be found.

The only real change is to install_check_class_requirements it now uses FilesystemIterator and checks classes for the Interface.

Thanks for your review! I applied two and replied to the other one.

One question is if the namespace should be Install/Requirements though so we can have other install time classes.

Ok I moved it to Install/Requirements to give us more flexibility if we need to add more install time hooks in the future for organization.

I also added a check for the install requirements text due to a suggestion from @ghost so we don't blindly require code.

I hid the other MR.

I also updated comments and the CR.

Rebased and also addressed @berdir's last concern.