Disclaimer: I don't claim to understand the inner workings of Zend. The following is my interpretation of the PHP source, fueled in great part by educated guesses. Even though I am fully confident in the conclusion, the terminology or details might be off. I 'd love to hear from anyone with experience in Zend internals on the matter.
The investigation
From the PHP parser we can see that when a class declaration is encountered the zend_do_early_binding function is called. Here is the code that handles the declaration of derived classes:
case ZEND_DECLARE_INHERITED_CLASS:
{
zend_op *fetch_class_opline = opline-1;
zval *parent_name;
zend_class_entry **pce;
parent_name = &CONSTANT(fetch_class_opline->op2.constant);
if ((zend_lookup_class(Z_STRVAL_P(parent_name), Z_STRLEN_P(parent_name), &pce TSRMLS_CC) == FAILURE) ||
((CG(compiler_options) & ZEND_COMPILE_IGNORE_INTERNAL_CLASSES) &&
((*pce)->type == ZEND_INTERNAL_CLASS))) {
if (CG(compiler_options) & ZEND_COMPILE_DELAYED_BINDING) {
zend_uint *opline_num = &CG(active_op_array)->early_binding;
while (*opline_num != -1) {
opline_num = &CG(active_op_array)->opcodes[*opline_num].result.opline_num;
}
*opline_num = opline - CG(active_op_array)->opcodes;
opline->opcode = ZEND_DECLARE_INHERITED_CLASS_DELAYED;
opline->result_type = IS_UNUSED;
opline->result.opline_num = -1;
}
return;
}
if (do_bind_inherited_class(CG(active_op_array), opline, CG(class_table), *pce, 1 TSRMLS_CC) == NULL) {
return;
}
/* clear unnecessary ZEND_FETCH_CLASS opcode */
zend_del_literal(CG(active_op_array), fetch_class_opline->op2.constant);
MAKE_NOP(fetch_class_opline);
table = CG(class_table);
break;
}
This code immediately calls zend_lookup_class to see if the parent class exists in the symbol table... and then diverges depending on whether the parent is found or not.
Let's first see what it does if the parent class is found:
if (do_bind_inherited_class(CG(active_op_array), opline, CG(class_table), *pce, 1 TSRMLS_CC) == NULL) {
return;
}
Going over to do_bind_inherited_class, we see that the last argument (which in this call is 1) is called compile_time. This sounds interesting. What does it do with this argument?
if (compile_time) {
op1 = &CONSTANT_EX(op_array, opline->op1.constant);
op2 = &CONSTANT_EX(op_array, opline->op2.constant);
} else {
op1 = opline->op1.zv;
op2 = opline->op2.zv;
}
found_ce = zend_hash_quick_find(class_table, Z_STRVAL_P(op1), Z_STRLEN_P(op1), Z_HASH_P(op1), (void **) &pce);
if (found_ce == FAILURE) {
if (!compile_time) {
/* If we're in compile time, in practice, it's quite possible
* that we'll never reach this class declaration at runtime,
* so we shut up about it. This allows the if (!defined('FOO')) { return; }
* approach to work.
*/
zend_error(E_COMPILE_ERROR, "Cannot redeclare class %s", Z_STRVAL_P(op2));
}
return NULL;
} else {
ce = *pce;
}
Okay... so it reads the parent and derived class names either from a static (from the PHP user's perspective) or dynamic context, depending on the compile_time status. It then tries to find the class entry ("ce") in the class table, and if it is not found then... it returns without doing anything in compile time, but emits a fatal error at runtime.
This sounds enormously important. Let's go back to zend_do_early_binding. What does it do if the parent class is not found?
if (CG(compiler_options) & ZEND_COMPILE_DELAYED_BINDING) {
zend_uint *opline_num = &CG(active_op_array)->early_binding;
while (*opline_num != -1) {
opline_num = &CG(active_op_array)->opcodes[*opline_num].result.opline_num;
}
*opline_num = opline - CG(active_op_array)->opcodes;
opline->opcode = ZEND_DECLARE_INHERITED_CLASS_DELAYED;
opline->result_type = IS_UNUSED;
opline->result.opline_num = -1;
}
return;
It seems that it is generating opcodes that will trigger a call to do_bind_inherited_class again -- but this time, the value of compile_time will be 0 (false).
Finally, what about the implementation of the class_exists PHP function? Looking at the source shows this snippet:
found = zend_hash_find(EG(class_table), name, len+1, (void **) &ce);
Great! This class_table variable is the same class_table that gets involved in the do_bind_inherited_class call we saw earlier! So the return value of class_exists depends on whether an entry for the class has already been inserted into class_table by do_bind_inherited_class.
The conclusions
The Zend compiler does not act on include directives at compile time (even if the filename is hardcoded).
If it did, then there would be no reason to emit a class redeclaration fatal error based on the compile_time flag not being set; the error could be emitted unconditionally.
When the compiler encounters a derived class declaration where the base class has not been declared in the same script file, it pushes the act of registering the class in its internal data structures to runtime.
This is evident from the last code snippet above, which sets up a ZEND_DECLARE_INHERITED_CLASS_DELAYED opcode to register the class when the script is executed. At that point the compile_time flag will be false and behavior will be subtly different.
The return value of class_exists depends on whether the class has already been registered.
Since this happens in different ways at compile time and at run time, the behavior of class_exists is also different:
- classes whose ancestors are all included in the same source file are registered at compile time; they exist and can be instantiated at any point in that script
- classes which have an ancestor defined in another source file are registered at runtime; before the VM executes the opcodes that correspond to the class definition in the source these classes do not exist for all practical purposes (
class_exists returns false, instantiating gives a fatal error)
Ais defined in the same file then BA (before) exists as well. – Atreus