the php manual isn't a book for a computer science course. If you want to know how a opcode cache works, the php manual is surelly not the best place to look at.
Anyway, all code you write in PHP is compiled to opcodes (and it is not the job of APC to compile the code).

> the php manual isn't a book for a computer science course.

Yes, you are correct in that the PHP manual is not the place for tutorials or a how-to-program guide. I apologize for the awkward phrasing. 

> If you want to know how a opcode cache works, the php manual is 
> surely not the best place to look at.

First, I am not interested in the general theory of opcode caching. Not all opcode caches work the same way. I want to know how APC works. 

> Anyway, all code you write in PHP is compiled to opcodes (and it
> is not the job of APC to compile the code).

Thanks for the clarification. You can understand the confusion, I'm sure, given the low-quality of the APC documentation, the presence of a function called apc_compile_file and the presence of a setting named apc.optimization. But let me rephrase as:

  When writing code, for example, I don't know under which conditions
  I may be creating code whose opcodes will not be cached by APC.

I'm asking for a precise specification of the APC module, not a tutorial. 

Recently, a blogger posted a quote from Rasmus about the behavior of APC with regards to __autoload (http://pooteeweet.org/blog/538). This triggered a discussion on PECL-DEV where Rasmus somewhat modified his statement (http://marc.info/?l=pecl-dev&m=116512075914909&w=2) after some speculation from various people about what APC would or wouldn't do.

I don't know about the documentation quality goals for PHP, but it should be possible for a reasonably experienced programmer to inspect reference-quality documentation and correctly answer questions about what APC does and doesn't do.

The main question that the current documentation doesn't answer is: under what conditions will APC cache a file's opcodes vs. the original file vs. not cache at all.

I just read the entire APC manual page (http://www.php.net/manual/en/ref.apc.php) and, while one could guess that APC performs some sort of automatic caching, I couldn't find a single sentence that actually stated this. Perhaps I missed it and you can point it out. This seems like something that should be explicit.

I also looked at apc_compile_file. It sounds as though any file can be compiled and cached. But Rasmus says there are conditions under which APC will not cache (http://marc.info/?l=pecl-dev&m=116515671021728&w=2). Can we document those conditions, at least the ones that APC tests for?

ok, so not caching all the (compiled) files can be seen like a bug and I'm sure somebody is working on that. My advise is: don't worry with that, because the situation will improve over the time.

Thanks for the reassurance nlopess, but it sounds like you could use a good APC reference yourself. Then you wouldn't have to guess as to whether the behavior was a bug or a feature.

I believe there are conditions under which APC will not and cannot cache the compiled code. Certainly, Rasmus seems to think so and I would think he would know. I also do not believe he considers it a bug in APC, although you would have to check with him. Finally, I don't know that anyone is working on this or intends to work on it.

There are hints throughout the Web about some of the conditions under which code will be or won't be cached. I'm trying to get these documented. I'm sure you want PHP to have the best documentation possible, so I'm puzzled by your resistance and why this bug report remains WONTFIX.

Because it's in the WONTFIX state, that also means no one else can comment on it besides you and me, so we're missing out from whatever wisdom others could contribute to this discussion. Would it be possible for you to re-open it?

Personally I would like to see tutorials, howto and best practices for each extension in the manual.. :)

Please use our mailing list (phpdoc@lists.php.net) for these kind of discussions.

Sounds reasonable, let's keep it open so someone will find and tackle this. Everyone should feel free to add knowledge and/or links to resources here too. In the very least we could find information to link to from ref.apc.

Also, the upcoming documentation style allows this type of information (like extension specific tutorials).

Assigning myself and Gopal to this one. Gopal said he will provide some of the material he had for APC that we can incorporate for the intermediate user into the manual so that you don't need to be a systems hacker to get it running in a nice manner

The files TECHNOTES and INSTALL both explain the functionality and operation of APC adequately.

I don't see the need for this report to be open any longer, I'm not sure when the files were added but the problem is no longer ...