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