Background:
I'm building an automated test framework for a PHP application, and I need a way to efficiently "stub out" classes which encapsulate communication with external systems. For example, when testing class X that uses DB wrapper class Y, I would like to be able to "swap in" a "fake" version of class Y while running automated tests on class X (this way I don't have to do full setup + teardown of the state of the real DB as part of the test).
Problem:
PHP allows "conditional includes", which means basically that include/require directives are handled as part of processing the "main" logic of a file, e.g.:
if (condition) {
require_once('path/to/file');
}
The problem is that I can't figure out what happens when the "main" logic of the included file calls "return". Are all of the objects (defines, classes, functions, etc.) in the included file imported into the file which calls include/require? Or does processing stop with the return?
Example:
Consider these three files:
A.inc
define('MOCK_Z', true);
require_once('Z.inc');
class Z {
public function foo() {
print "This is foo() from a local version of class Z.\n";
}
}
$a = new Z();
$a->foo();
B.inc
define('MOCK_Z', true);
require_once('Z.inc');
$a = new Z();
$a->foo();
Z.inc
if (defined ('MOCK_Z')) {
return true;
}
class Z {
function foo() {
print "This is foo() from the original version of class Z.\n";
}
}
I observe the following behavior:
$ php A.inc
> This is foo() from a local version of class Z.
$ php B.inc
> This is foo() from the original version of class Z.
Why This is Strange:
If require_once() included all of the defined code objects, then "php A.inc" ought to complain with a message like
Fatal error: Cannot redeclare class Z
And if require_once() included only the defined code objects up to "return", then "php B.inc" ought to complain with a message like:
Fatal error: Class 'Z' not found
Question:
Can anyone explain exactly what PHP is doing, here? It actually matters to me because I need a robust idiom for handling includes for "mocked" classes.
According to php.net, if you use a return statement, it'll return execution to script that called it. Which means, require_once will stop executing, but the overall script will keep running. Also, examples on php.net show that if you return a variable within an included file, then you can do something like $foo = require_once('myfile.php'); and $foo will contain the returned value from the included file. If you don't return anything, then $foo is 1 to show that require_once was successful. Read this for more examples.
And I don't see anything on php.net that says anything specifically about how the php interpreter will parse included statements, but your testing shows that it first resolves class definitions before executing code in-line.
UPDATE
I added some tests as well, by modifying Z.inc as follows:
$test = new Z();
echo $test->foo();
if (defined ('MOCK_Z')) {
return true;
}
class Z {
function foo() {
print "This is foo() from the original version of class Z.\n";
}
}
And then tested on the command line as follows:
%> php A.inc
=> This is foo() from a local version of class Z.
This is foo() from a local version of class Z.
%> php B.inc
=> This is foo() from the original version of class Z.
This is foo() from the original version of class Z.
Obviously, name hoisting is happening here, but the question remaining is why there are no complaints about re-declarations?
UPDATE
So, I tried to declare class Z twice in A.inc and I got the fatal error, but when I tried to declare it twice in Z.inc, I didn't get an error. This leads me to believe that the php interpreter will return execution to the file that did the including when a fatal runtime error occurs in an included file. That is why A.inc did not use Z.inc's class definition. It was never put into the environment, because it caused a fatal error, returning execution back to A.inc.
UPDATE
I tried the die(); statement in Z.inc, and it actually does stop all execution. So, if one of your included scripts has a die statement, then you will kill your testing.
Okay so behavior of the return statement in PHP included files is to return control to the parent in execution. That means the classes definitions are parsed and accessible during the compile phase. For instance, if you change the above to the following
a.php:
<?php
define('MOCK_Z', true);
require_once('z.php');
class Z {
public function foo() {
print "This is foo() from a local version of class Z in a.php\n";
}
}
$a = new Z();
$a->foo();
?>
b.php:
<?php
define('MOCK_Z', true);
require_once('z.php');
$a = new Z();
$a->foo();
?>
z.php:
<?php
if (defined ('MOCK_Z')) {
echo "MOCK_Z definition found, returning\n";
return false;
}
echo "MOCK_Z definition not found defining class Z\n";
class X { syntax error here ; }
class Z {
function foo() {
print "This is foo() from the original version of class Z.\n";
}
}
?>
then php a.php and php b.php will both die with syntax errors; which indicates that the return behavior is not evaluated during compile phase!
So this is how you go around it:
z.php:
<?php
$z_source = "z-real.inc";
if ( defined(MOCK_Z) ) {
$z_source = "z-mock.inc";
}
include_once($z_source);
?>
z-real.inc:
<?php
class Z {
function foo() {
print "This is foo() from the z-real.inc.\n";
}
}
?>
z-mock.inc:
<?php
class Z {
function foo() {
print "This is foo() from the z-mock.inc.\n";
}
}
?>
Now the inclusion is determined at runtime :^) because the decision is not made until $z_source value is evaluated by the engine.
Now you get desired behavior, namely:
php a.php gives:
Fatal error: Cannot redeclare class Z in /Users/masud/z-real.inc on
line 2
and php b.php gives:
This is foo() from the z-real.inc.
Of course you can do this directly in a.php or b.php but doing the double indirection may be useful ...
NOTE
Having SAID all of this, of course this is a terrible way to build stubs hehe for unit-testing or for any other purpose :-) ... but that's beyond the scope of this question so I shall leave it to your good devices.
Hope this helps.
It looks like the answer is that class declarations are compile-time, but duplicate class definition errors are run-time at the point in the code that the class is declared. The first time a class definition is in a parsed block, it is immediately made available for use; by returning from an included file early, you aren't preventing class declaration, but you are bailing out before the error is thrown.
For example, here are a bunch of class definitions for Z:
$ cat A.php
<?php
error_reporting(-1);
$init_classlist = get_declared_classes();
require_once("Z.php");
var_dump(array_diff(get_declared_classes(), $init_classlist));
class Z {
function test() {
print "Modified Z from A.php.\n";
}
}
$z = new Z();
$z->test();
return;
class Z {
function test() {
print "Another Z from A.php.\n";
}
}
$ cat Z.php
<?php
echo "In Z.php!\n";
return;
class Z {
function test() {
print "Original Z.\n";
}
}
When A.php is called, the following is produced:
In Z.php!
array(0) {
}
Modified Z from A.php.
This shows that the declared classes don't change upon entering Z.php - the Z class is already declared by A.php further down the file. However, Z.php never gets a change to complain about the duplicate definition due to the return before the class declaration. Similarly, A.php doesn't get a chance to complain about the second definition in the same file because it also returns before the second definition is reached.
Conversely, removing the first return; in Z.php instead produces:
In Z.php!
Fatal error: Cannot redeclare class Z in Z.php on line 4
By simply not returning early from Z.php, we reach the class declaration, which has a chance to produce its run-time error.
In summary: class declaration is compile-time, but duplicate definition errors are run-time at the point the class declaration appears in the code.
(Of course, having not confirmed this with the PHP internals, it might be doing something completely different, but the behavior is consistent with my description above. Tested in PHP 5.5.14.)
This is the closest thing I could find in the manual:
If there are functions defined in the included file, they can be used in the main file independent if they are before return() or after. If the file is included twice, PHP 5 issues fatal error because functions were already declared, while PHP 4 doesn't complain about functions defined after return().
And this is true regarding functions. If you define the same function in A and Z (after the return) with PHP 5, you'll get a fatal error as you expect.
However, classes seem to fall back to PHP 4 behavior, where it doesn't complain about functions defined after return. To me this seems like a bug, but I don't see where the documentation says what should happen with classes.
I've thought about this for a while now, and nobody has been able to point me to a clear and consistent explanation for the way PHP (up to 5.3 anyway) processes includes.
I conclude that it would be better to avoid this issue entirely and achieve control over "test double" class substitution via autoloading:
spl-autoload-register
In other words, replace the includes at the top of each PHP file with a require_once() which "bootstraps" a class which defines the logic for autoloading. And when writing automated tests, "inject" alternative autoloading logic for the classes to be "mocked" at the top of each test script.
It will naturally require a good deal of effort to modify existing code to follow this approach, but the effort appears to be worthwhile both to improve testability and to reduce the total number of lines in the codebase.
Related
Say I have this b.php file
<?php
function ff() { echo "B"; }
and this a.php file
<?php
if ( true ) {
include ("b.php");
ff();
exit;
}
function ff() { echo "A"; }
Running php a.php gives
PHP Fatal error: Cannot redeclare ff()
Hmm, ok. So what if I re-run php a.php with this a.php code
<?php
if ( true ) {
include ("b.php");
ff();
exit;
}
else {
function ff() { echo "A"; }
}
This time that works, and I get B as expected.
In the first case, PHP reads and parse the whole file. Meaning, during compilation it sees the 2 same functions declarations, though the exit guarantees that at runtime we won't get up to the 2nd ff().
However in the 2nd case, it sees it at run time, but the compiler is not upset about seeing this function declared twice...
Seems the compiler behaves differently based on if the function is top-level or not... while
All functions and classes in PHP have the global scope
(the doc)
Now, how to turn that into a non opinion-based question :)
So it seems the options are either to rename ff to something like ffa and ffb, or add a long else { ... }. or change the whole structure...
Is this how PHP works, or that can be changed in the settings?
In the PHP documentation it says:
Classes should be defined before instantiation (and in some cases this is a requirement).
can some one give me a example of a class that can not be instantiated unless it was previously defined?
if (true) {
new Foo;
class Foo { }
}
The parsing rules are the same as for functions: if they're defined in the "top level" of a file, they're parsed during, well, parsing of the file. If they're defined inside a piece of code which requires runtime evaluation, then the class or function will only be defined when the code is executed, in which case you can't use it before it's been "executed".
<?php
// Top Level
trait T {
}
$c = new C();
class C {
use T;
}
With trait, this code occurs error (Class 'C' not found in...).
I'm building a class, which has some of its methods' bodies defined in other php files.
I have to do this, because although most functions are small, sane, and written by hand, a couple functions need to be auto-generated by another script I made.
The problem is that although the methods get called, the return statements in those methods don't seem to execute.
The general structure is like this:
MyClass.php:
<?php
class MyClass
{
public function foo()
{
include "myclass-foo-body.php";
}
}
?>
myclass-foo-body.php:
<?php
echo "foo()"; // This executes and outputs as normal.
return 42; // This does not appear to actually execute or return anything.
?>
test.php:
<?php
include_once "MyClass.php";
$bar = new MyClass();
$foo = $bar->foo();
var_dump($foo); // Ends up being NULL instead of 42.
?>
So, what am I doing wrong here?
Are function/method bodies not actually supposed to be included from another php file?
I appear to have followed the documentation for php's include, but I seem to be missing crucial information.
(I couldn't find any existing questions on this subject, so hopefully this isn't a dupe!)
Thanks!
Return value of your body file will be the return value of your include call so you should do it like below.
public function foo()
{
return include "myclass-foo-body.php";
}
Your method foo is not returning anything.
A return in the included file terminates the processing of the included file.
PHP Manual
It is possible to execute a return statement inside an included file
in order to terminate processing in that file and return to the script
which called it.
a.php
<?php
echo "AAA\n";
if(class_exists('NotImplementedException')) {
echo "BBB\n";
return;
echo "DDD\n";
}
echo "CCC\n";
/**
* Thrown when a feature is not yet implemented.
*/
class NotImplementedException extends Exception {}
b.php
<?php
include 'a.php';
include 'a.php';
When I run b.php I get:
AAA
BBB
PHP Fatal error: Cannot redeclare class NotImplementedException in /home/mark/Tests/IncludeTwice/a.php on line 15
What's going on here? The output I would expect is
AAA
CCC
(class gets declared for first time)
AAA
BBB
(execution stops)
To those saying "the interpreter scans and parses the whole file first": then why does this work?:
<?php
class A{}
if(!class_exists('A')) {
class A{}
}
I think one part is a bug...
The PHP interpreter works differently if you are extending a class.
This works:
<?php
class a {}
exit();
class a extends Exception {}
?>
This does not:
<?php
class a extends Exception {}
exit();
class a {}
?>
From what I can see in the PHP 5.4.0 source, there are two different functions that handle the binding of classes: do_bind_class:4494 for standalone classes and do_bind_inherited_class:4533 for inherited classes (ones that use the extend keyword).
The stand-alone function has a conditional that ignores duplicate class definitions at compile time in case it is never hit at runtime. The inherited class version is missing this conditional (maybe on purpose, maybe not).
I would patch the inherited function to have the same conditional, test and submit to the developers.
And the other part is a feature...
As for your conditional class piece: I believe that PHP will load your class at compile-time if it is declared at global scope, but if it is contained inside a block, it will not be loaded until it is executed.
This works:
<?php
$a = new A();
//{
class A {}
//}
?>
This doesn't work, even though it is logically identical:
<?php
$a = new A();
{
class A {}
}
?>
When you combine these two pieces of functionality, your problem arises since your class is both an inherited class and declared at global scope.
You need to move the class declaration into an else statement from the class_exists() call. You are declaring it both times that you include a.php. The return doesn't prevent the file from being parsed, which includes the class declaration in this case. So while the script execution doesn't make it past your return, PHP sees that you've declared NotImplementedException more than once.
Think of it as if you put a bunch of syntactically incorrect code after a return. The parser will still give you an error even though the code execution won't make it there.
I'm trying to create a class TestClass that's divided over several files. I have split it over 3 files where the first file TestClassPart1.php has the start of the class class TestClass { and the last file TestClassPart3.php has the closing bracket of the class. These are the 3 files
//TestClassPart1.php
<?php
class TestClass {
public function func1(){
echo "func 1";
}
//TestClassPart2.php
<?php
public function func2(){ echo "func 2"; }
//TestClassPart3.php
<?php
public function func3(){ echo "func 3"; }
}
I then recombine in the actual class file called TestClass.phpso TestClass.php is just the glue of all 3 files.
<?php
require 'TestClassPart1.php';
require 'TestClassPart2.php';
require 'TestClassPart3.php';
I thought this should work, but when I try to create an instance of TestClass and call one of the functions, I get parse error, expecting T_FUNCTION' in C:\wamp\www\TestClassPart1.php on line 5. Line 5 is the } of func1()
<?php
require 'TestClass.php';
$nc = new TestClass();
$nc->func1();
Shouldn't this work? I thought you could spread a class over several files no problem. Am I doing it wrong?
When you require a file, PHP will parse and evaluate the contents.
You class is incomplete, so when PHP parses
class TestClass {
public function func1(){
echo "func 1";
}
it's not able to make sense of the class, because the closing } is missing.
Simple as that.
And to anticipate your next question. This
class Foo
{
include 'methods.php'
}
will not work either.
From the PHP Manual on OOP 4 (couldnt find it in 5)
You can NOT break up a class definition into multiple files. You also can NOT break a class definition into multiple PHP blocks, unless the break is within a method declaration. The following will not work:
<?php
class test {
?>
<?php
function test() {
print 'OK';
}
}
?>
However, the following is allowed:
<?php
class test {
function test() {
?>
<?php
print 'OK';
}
}
?>
If you are looking for Horizontal Reuse, either wait for PHP.next, which will include Traits or have a look at
Can I include code into a PHP class?
I had this same thought a while back as a purely academic interest. It's not directly possible to do what you're asking, although you are able to use PHP to produce PHP that then gets evaluated by the server.
Long story short:
Don't bother
Short story long:
it adds a level of insecurity to your classing system as it becomes harder to control file access.
it slows down the compilation/caching of pages
you really don't need to force a square peg into a round hole.
Instead: use proper OOP practices of separating functionality into classes and extending existing classes.
If you must do it this way, you can use include_once() to directly shove a file into your script.