Deprecate \Drupal\Component\Assertion\Handle::register()

Patch attached that does the following:

1) Adds @trigger_error, @deprecated and @see in Drupal/Component/Assertion/Handle class.
2) Replaces calls to Handle::register() function with assert_options(ASSERT_EXCEPTION, TRUE);

Still need to add the change notice.

Comments addressed in #4 & also re-rolled the patch against 8.8.x branch.

Looks like we still need to create a change record although I feel like there's not more to say than what the comment already does. However, because it is in example.settings.local.php, I suspect this will actually affect *a lot* of dev installations, so the additional visibility seems useful.

Here's the draft - https://www.drupal.org/node/3105918.

Issues adding new deprecations (for removal in Drupal 10) should be moved to 9.1.x

Drupal 8.8 was the final release to introduce new deprecations that will be removed in Drupal 9. This means that all new deprecations in 8.9 and higher will be retained in Drupal 9 and marked for removal in Drupal 10 instead.

@Krzysztof Domański, why back to NW?

+@trigger_error('The ' . __NAMESPACE__ . '\Handle is deprecated in Drupal 8.8.0 and will be removed before Drupal 9.0.0. Instead, replace the calls to Handle::register() method with assert_options(ASSERT_EXCEPTION, TRUE).', E_USER_DEPRECATED);

+ * @deprecated in Drupal 8.8.0 and will be removed before Drupal 9.0.0.

1. It won't be backported to D8.8 so it should be deprecated in drupal:9.1.0 and is removed from drupal:10.0.0.

all new deprecations in 8.9 and higher will be retained in Drupal 9 and marked for removal in Drupal 10 instead.

2. See also what is the correct the PHPdoc text and trigger_error() message format on the Drupal core deprecation policy.

Thanks. CR updated.

Oops.

re-roll around #3110862: Remove simpletest module from core and #3063182: Remove PHPUnit 4.8 class aliasing BC layer and who knows how many other little use changes.

Sorry for the noise, I forgot to update the deprecation message.

It seems a bit pointless here but we usually have a test for deprecation messages.

Yeah, maybe a little pointless but doable so test included. Also the style fix.

Woops... some whitespace errors.

#23 is good for 9.4.x but needs a separate version for 10.0.x as core/tests/bootstrap.php has changed.

Oh we will need to update the version to 9.4.x, can we still remove this in 10.0.x as it seems unlikely to be used outside of core?

Added deprecation removal for 10.x
Updated deprecation messages for 9.4.x

So most new deprecations now should be for 10.1.x for removal in 11.x, but I think there's a couple of good reasons to do something here before that:

1. We have docs telling people to use this in example.settings.local.php - at a minimum those docs should be updated to not recommend it if we know we're going to remove it.

2. This is part of updating the platform requirements.

3. There shouldn't be any contrib impact at all.

I was about to write that given the above, we should deprecate in 9.5.0 for removal in 11.0.0, but... if people are using that settings.local.php snippet, are we suddenly going to start triggering a deprecation error on every request? That seems annoying for the last minor release. And then, given the deprecation error is suppressed and no-one runs phpstan on settings.local.php, what is the deprecation error going to do there? We probably need something stronger.

So... I am not sure what to do here. I kind of feel like we should add an un-suppressed deprecation error in 10.0.x or 10.1.x, specifically to loudly warn people that they need to sort out their settings.local.php so they don't get a fatal error when the update to Drupal 11. But that is unusual so more opinions would be good.

Regardless, I think it would be a good idea to commit a minimal patch changing settings.local.php so we stop recommending this, maybe even back to 9.4.x.

Bumping this one to 10.0.x (for now).

Opened #3295650: Stop recommending using \Drupal\Component\Assertion\Handle::register() in example.settings.local.php to deal with:

Regardless, I think it would be a good idea to commit a minimal patch changing settings.local.php so we stop recommending this, maybe even back to 9.4.x.

Added a patch for Drupal 10.0.x.

Patch #34 passes the tests and It's green, It's ready for review.

Based on #32 I think this part of it should be 10.1.x; thanks for splitting off #3295650: Stop recommending using \Drupal\Component\Assertion\Handle::register() in example.settings.local.php.

As per comment #36, patch #34 has been re-rolled to work Drupal on 10.1.x

+++ /dev/null
@@ -1,25 +0,0 @@
- * Handler for runtime assertion failures.
- *
- * @ingroup php_assert
- *
- * @todo Deprecate this class. https://www.drupal.org/node/3054072
- */
-class Handle {

This should be deprecated (in 10.1.x for removal in 11.0.0, not removed - I think the 9.x patches in this issue already did that.

#39 looks correct to me for 10.1.x only.

+++ b/core/lib/Drupal/Component/Assertion/Handle.php
@@ -2,12 +2,17 @@
 
+@trigger_error(__NAMESPACE__ . '\Handle is deprecated in drupal:10.1.0 and is removed from drupal:11.0.0. Instead, use assert_options(ASSERT_EXCEPTION, TRUE). See https://drupal.org/node/3105918', E_USER_DEPRECATED);
+

One more question - should we remove the @ here so that actual sites get the deprecation message (if they're running E_DEPRECATED) - because this is most likely to be loaded from settings.local.php which doesn't get test covrage.

Updated patch by removing the @trigger_error

What @catch meant in #41 was to leave the trigger_error() line in place, just remove the @ at the start of the line so the deprecation is not silenced.

@longwave,

I made the changes you required at comments #43

Needs review.

#43 was addressed, looks good

With PHP 8.3 the assert_options() is deprecated, looking for opinions in #3375693: Fix deprecated assert_options() function usage for PHP 8.3