16f6c0aecf
Inline adoc files when they are included exactly once. Also fix language tags because this inlining gives us better information on what language the code is written in.
76 lines
2.2 KiB
Plaintext
76 lines
2.2 KiB
Plaintext
== Why is this an issue?
|
|
|
|
At root, ``++require++``, ``++require_once++``, ``++include++``, and ``++include_once++`` all perform the same task of including one file in another.
|
|
However, the way they perform that task differs, and they should not be used interchangeably.
|
|
|
|
* ``++require++`` includes a file but generates a fatal error if an error occurs in the process.
|
|
|
|
* ``++include++`` also includes a file, but generates only a warning if an error occurs.
|
|
|
|
Predictably, the difference between ``++require++`` and ``++require_once++`` is the same as the difference between ``++include++`` and ``++include_once++``.
|
|
The `_once` versions ensure that the specified file is only included once.
|
|
|
|
=== What is the potential impact?
|
|
|
|
Including the same file multiple times could have unpredictable results, the `_once` versions are preferred.
|
|
Additionally, as ``++include_once++`` generates only warnings, it should be used only when the file is being included conditionally, i.e. when all possible error conditions have been checked beforehand.
|
|
|
|
== How to fix it
|
|
|
|
Rewrite your code to only contain `require_once` and conditional `include_once` calls.
|
|
|
|
=== Code examples
|
|
|
|
==== Noncompliant code example
|
|
|
|
[source,php,diff-id=1,diff-type=noncompliant]
|
|
----
|
|
include 'code.php'; //Noncompliant; not a "_once" usage and not conditional
|
|
include $user.'_history.php'; // Noncompliant
|
|
require 'more_code.php'; // Noncompliant; not a "_once" usage
|
|
----
|
|
|
|
==== Compliant solution
|
|
|
|
[source,php,diff-id=1,diff-type=compliant]
|
|
----
|
|
require_once 'code.php';
|
|
if (is_member($user)) {
|
|
include_once $user.'_history.php';
|
|
}
|
|
require_once 'more_code.php';
|
|
----
|
|
|
|
== Resources
|
|
|
|
=== Documentation
|
|
|
|
* https://www.php.net/manual/en/function.require-once.php[PHP Manual - require-once]
|
|
* https://www.php.net/manual/en/function.require.php[PHP Manual - require]
|
|
* https://www.php.net/manual/en/function.include-once.php[PHP Manual - include-once]
|
|
* https://www.php.net/manual/en/function.include.php[PHP Manual - include]
|
|
|
|
ifdef::env-github,rspecator-view[]
|
|
|
|
'''
|
|
|
|
== Implementation Specification
|
|
|
|
(visible only on this page)
|
|
|
|
=== Message
|
|
|
|
Replace "xxx" with "yyy".
|
|
|
|
|
|
'''
|
|
|
|
== Comments And Links
|
|
|
|
(visible only on this page)
|
|
|
|
=== on 19 May 2015, 15:51:55 Linda Martin wrote:
|
|
Reviewed
|
|
|
|
endif::env-github,rspecator-view[]
|