rspec/rules/S1998/php/rule.adoc

== Why is this an issue?

In PHP, references allow you to create multiple names for the same variable, enabling you to access and manipulate its value through different identifiers.
They are denoted by the ampersand symbol & placed before the variable name during declaration or assignment.

Any modification a method makes to a function parameter passed by reference will also be made to the original value.

This feature can be difficult to use correctly, particularly if the callee is not expecting a reference.

The improper use of references in function calls can make code less efficient rather than more efficient.

=== What is the potential impact?

While references can provide flexibility and efficiency in certain scenarios, they can also introduce complexity and potential pitfalls.
Incorrect usage of references may lead to unexpected behavior, difficult-to-debug code, and unintended side effects.
It's important to exercise caution and fully understand the implications before employing references.

== How to fix it in Core PHP

Refactor your code to not pass a reference as a function parameter.

=== Code examples

==== Noncompliant code example

[source,php,diff-id=1,diff-type=noncompliant]
----
myfun(&$name);  // Noncompliant
----

==== Compliant solution

[source,php,diff-id=1,diff-type=compliant]
----
myfun($name);
----

== Resources

=== Standards

* CWE - https://cwe.mitre.org/data/definitions/374[CWE-374 - Weakness Base Passing Mutable Objects to an Untrusted Method]


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

'''

== Implementation Specification

(visible only on this page)

=== Message

Remove the '&' to pass "$xxx" by value.


'''

== Comments And Links

(visible only on this page)

=== on 19 Sep 2014, 15:49:22 Freddy Mallet wrote:
@Ann, I guess you can link this rule to \http://cwe.mitre.org/data/definitions/374.html.  

=== on 15 Oct 2014, 09:53:48 Linda Martin wrote:
\[~ann.campbell.2] Your description made me read the PHP Manual, and in addition to what you already have written I saw the following: 

____
As of PHP 5.3.0, you will get a warning saying that "call-time pass-by-reference" is deprecated  [...] *And as of PHP 5.4.0, call-time pass-by-reference was removed, so using it will raise a fatal error.*

____

I don't know if it was already there when you read the Manual, in any case I think it would be worth mentioning it in the description. And why note even quote the Manual ? 


WDYT ?

=== on 15 Oct 2014, 11:50:37 Ann Campbell wrote:
\[~linda.martin] I did not see the removal notice. Thanks for finding it. I've updated the description per your recommendations.

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