rspec/rules/S4824/php/rule.adoc

== Why is this an issue?

In PHP, references provide a way to access the same variable content using different names.

When a reference is used in a ``++foreach++`` loop instead of using a simple variable, the reference remains assigned and keeps its "value" which is a reference, even after the ``++foreach++`` execution.

=== What is the potential impact?

Not unsetting the reference can lead to bugs later in the code, as most of the time, this behavior is different from what the developer is expecting.
For example, the reference may be used incorrectly with the previous value.

To avoid unexpected side effects, it is recommended to always ``++unset++`` a reference that is used in a ``++foreach++`` loop.

== How to fix it in Core PHP

Unset the reference that is used in the ``++foreach++`` loop.

=== Code examples

==== Noncompliant code example

[source,php,diff-id=1,diff-type=noncompliant]
----
$arr = array(1, 2, 3);
foreach ($arr as &$value) { // Noncompliant; $value is still alive after the loop and references the last item of the array: $arr[2]
    $value = $value * 2;
}
$value = 'x';
----

==== Compliant solution

[source,php,diff-id=1,diff-type=compliant]
----
$arr = array(1, 2, 3);
foreach ($arr as &$value) { // Compliant; there is no risk to use by mistake the content of $value pointing to $arr[2]
    $value = $value * 2;
}
unset($value);
$value = 'x';
----

== Resources

=== Documentation

PHP Documentation:

* https://www.php.net/manual/en/language.references.php[References]
* https://php.net/manual/en/control-structures.foreach.php[Foreach]

=== Articles & blog posts

* https://schlueters.de/blog/archives/141-References-and-foreach.html[References and Foreach]

ifdef::env-github,rspecator-view[]

'''

== Implementation Specification

(visible only on this page)

include::message.adoc[]

include::highlighting.adoc[]

endif::env-github,rspecator-view[]