[policy, then docs] Change how we deprecate classes

Problem/Motivation

In https://www.drupal.org/core/deprecation#how-class we recommend adding the @trigger_error to the MAIN part of the PHP file outside of the class. This has several problems.

• For unit tests if they are run altogether the code is only loaded once so you have different results if the test is executed on its own or if the test is executed along side all the other tests and one of the other tests includes the same deprecated code
• Sometimes in core we check if a class exists but that in and of itself does not mean the the class is actually used. eg. plugins and route controllers - see #2935610-19: Remove or deprecate MediaDeleteMultipleConfirmForm and it's route definition for example.

Proposed resolution

Change the advice to move the @trigger_error() into the constructor to over come this and move all the deprecations in core to be consistent.

Proposed update to docs

Abstract classes, interfaces and traits

Add @trigger_error('...', E_USER_DEPRECATED) under the namespace declaration. Add an @deprecated and @see phpdoc annotations to the class docblock. For example:

<?php

namespace Drupal\datetime\Tests\Views;
	
@trigger_error('The ' . __NAMESPACE__ . '\DateTimeHandlerTestBase is deprecated in Drupal 8.4.0 and will be removed before Drupal 9.0.0. Instead, use \Drupal\Tests\BrowserTestBase. See http://drupal.org/node/the-change-notice-nid.', E_USER_DEPRECATED);

/**
 * Base class for testing datetime handlers.
 *
 * @deprecated in Drupal 8.4.0 and will be removed before Drupal 9.0.0. Use
 *  \Drupal\Tests\BrowserTestBase.
 *
 * @see http://drupal.org/node/the-change-notice-nid
 */
abstract class DateTimeHandlerTestBase extends HandlerTestBase {

Concrete classes

Concrete, instantiated classes
Add @trigger_error('...', E_USER_DEPRECATED) to the constructor. If there is no constructor, add one and ensure it calls the parent constructor. Add an @deprecated and @see phpdoc annotations to the class docblock. For example:

<?php

namespace Drupal\taxonomy;

use Drupal\Core\Entity\EntityManagerInterface;
use Drupal\Core\Entity\EntityTypeInterface;
use Drupal\Core\Entity\EntityViewBuilder;
use Drupal\Core\Language\LanguageManagerInterface;
use Drupal\Core\Theme\Registry;

/**
 * View builder handler for taxonomy terms.
 *
 * @deprecated in drupal:8.4.0 and is removed from drupal:9.0.0. Use
 * \Drupal\Core\Entity\EntityViewBuilder instead.
 *
 * @see https://www.drupal.org/node/2924233
 */
class TermViewBuilder extends EntityViewBuilder {

  /**
   * {@inheritdoc}
   */
  public function __construct(EntityTypeInterface $entity_type, EntityManagerInterface $entity_manager, LanguageManagerInterface $language_manager, Registry $theme_registry = NULL) {
    @trigger_error(__NAMESPACE__ . '\TermViewBuilder is deprecated in drupal:8.4.0 and is removed from drupal:9.0.0. Use \Drupal\Core\Entity\EntityViewBuilder instead. See https://www.drupal.org/node/2924233.', E_USER_DEPRECATED);
    parent::__construct($entity_type, $entity_manager, $language_manager, $theme_registry);
  }

}

Remaining tasks

None. The policy docs are updated and there is a followup to implement this in core.

User interface changes

None

API changes

None

Data model changes

None