Problem/Motivation

Subsequent to the application of #2853503 assert() calls using the eval syntax are no longer allowed in the Drupal codebase, but code.api.php has not been updated to match:

https://api.drupal.org/api/drupal/core%21core.api.php/group/php_assert/8...

Proposed resolution

Update it. This was originally planned to be performed as part of #2916440 but that issue is being postponed to Drupal 8.7 when support for PHP 5 is finally dropped. A draft of the change from the git patch of that issue is as follows:

diff --git a/core/core.api.php b/core/core.api.php
index 3b0765104b..5045fc55fa 100644
--- a/core/core.api.php
+++ b/core/core.api.php
@@ -1221,10 +1221,6 @@
  * verified with standard control structures at all times, not just checked in
  * development environments with assert() statements on.
  *
- * When runtime assertions fail in PHP 7 an \AssertionError is thrown.
- * Drupal uses an assertion callback to do the same in PHP 5.x so that unit
- * tests involving runtime assertions will work uniformly across both versions.
- *
  * The Drupal project primarily uses runtime assertions to enforce the
  * expectations of the API by failing when incorrect calls are made by code
  * under development. While PHP type hinting does this for objects and arrays,
@@ -1232,21 +1228,12 @@
  * complex data structures such as cache and render arrays. They ensure that
  * methods' return values are the documented datatypes. They also verify that
  * objects have been properly configured and set up by the service container.
- * Runtime assertions are checked throughout development. They supplement unit
- * tests by checking scenarios that do not have unit tests written for them,
- * and by testing the API calls made by all the code in the system.
- *
- * When using assert() keep the following in mind:
- * - Runtime assertions are disabled by default in production and enabled in
- *   development, so they can't be used as control structures. Use exceptions
- *   for errors that can occur in production no matter how unlikely they are.
- * - Assert() functions in a buggy manner prior to PHP 7. If you do not use a
- *   string for the first argument of the statement but instead use a function
- *   call or expression then that code will be evaluated even when runtime
- *   assertions are turned off. To avoid this you must use a string as the
- *   first argument, and assert will pass this string to the eval() statement.
- * - Since runtime assertion strings are parsed by eval() use caution when
- *   using them to work with data that may be unsanitized.
+ * They supplement unit tests by checking scenarios that do not have unit tests
+ * written for them.
+ *
+ * There are two php settings which affect runtime assertions. The first,
+ * assert.exception, should always be set to 1. The second is zend.assertions.
+ * Set this to -1 in production and 1 in development.
  *
  * See https://www.drupal.org/node/2492225 for more information on runtime
  * assertions.

This issue is marked novice as there is no executable code change.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Aki Tendo created an issue. See original summary.

ioana apetri’s picture

Assigned: Unassigned » ioana apetri
ioana apetri’s picture

Assigned: ioana apetri » Unassigned
Status: Active » Needs review
FileSize
2.42 KB

I created the patch. Please review. Thanks:)

Aki Tendo’s picture

Status: Needs review » Reviewed & tested by the community

Looks good to me, thanks.

  • larowlan committed 402d95a on 8.6.x
    Issue #2939242 by yo30: Update Drupal Documentation to reflect that...

  • larowlan committed 35eca78 on 8.5.x
    Issue #2939242 by yo30: Update Drupal Documentation to reflect that...
larowlan’s picture

Status: Reviewed & tested by the community » Fixed

Committed as 402d95a and pushed to 8.6.x

Cherry-picked as 35eca78 and pushed to 8.5.x.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.