Derived class defined later in the same file "does not exist"?

class, extends, include, php, require

Solution

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)

Problem

Original source