diff --git a/internals2/counter.xml b/internals2/counter.xml
new file mode 100644
index 0000000000..c0aa120aea
--- /dev/null
+++ b/internals2/counter.xml
@@ -0,0 +1,692 @@
+
+
+
+ The "counter" Extension - A Continuing Example
+
+
+ Preface
+
+ Throughout this Zend documentation, references are made to an example module
+ in order to illustrate various concepts. The "counter" extension is this
+ example, a fictional yet functional Zend module which strives to use as much
+ of the Zend API as is reasonably possible. This short chapter describes the
+ userland interface to the completed extension.
+
+
+
+
+ "counter" serves no practical purpose whatsoever, as the functionality it
+ provides is far more effectively implemented by appropriate userland code.
+
+
+
+
+
+ &reftitle.setup;
+
+
+ &reftitle.intro;
+
+
+ The "counter" extension provides any number of counters to PHP code using it
+ which reset at times determined by the caller.
+
+
+
+ There are three interfaces to "counter": basic, extended, and objective. The
+ basic interface provides a single counter controlled by INI settings and
+ function calls. The extended interface provides an arbitrary number of named
+ counter resources which may optionally persist beyond the lifetime of a
+ single PHP request. The objective interface combines both the basic and
+ extended interfaces into a Counter class.
+
+
+
+
+ &reftitle.runtime;
+
+ &extension.runtime;
+
+ &ini.php.constants;
+
+
+
+
+ counter.reset_time
+ integer
+
+
+
+ counter.reset_time tells "counter" to reset the
+ counter used by the basic interface. It may be any of the
+ COUNTER_RESET_* constants (see below).
+
+
+
+
+
+ counter.save_path
+ string
+
+
+
+ Tells "counter" where to save data that has to persist between
+ invocations of PHP (i.e. any counter that has COUNTER_RESET_NEVER or
+ COUNTER_FLAG_SAVE). A file will be created at this path, which must be
+ readable and writeable to whatever user PHP is running as.
+
+
+
+
+
+ counter.initial_value
+ integer
+
+
+
+ Sets the initial value of the counter used by the basic interface
+ whenever it is reset.
+
+
+
+
+
+
+
+
+ &reftitle.resources;
+
+
+ The "counter" extension defines one resource type, a counter.
+
+
+
+
+
+
+ &reftitle.constants;
+ &extension.constants;
+
+
+
+
+ COUNTER_FLAG_PERSIST
+ (integer)
+
+
+
+ A counter with this flag will be created as a persistent resource.
+
+
+
+
+
+ COUNTER_FLAG_SAVE
+ (integer)
+
+
+
+ A counter with this flag will be saved between invocations of PHP.
+
+
+
+
+
+ COUNTER_FLAG_NO_OVERWRITE
+ (integer)
+
+
+
+ This flag causes counter_create to avoid overwriting
+ an existing named counter with a new one.
+
+
+
+
+
+ COUNTER_META_NAME
+ (string)
+
+
+
+ Pass this constant to get the name of a counter resource or object.
+
+
+
+
+
+ COUNTER_META_IS_PERISTENT
+ (string)
+
+
+
+ Pass this constant to determine whether a counter resource or object is
+ persistent (has the COUNTER_FLAG_PERSIST flag).
+
+
+
+
+
+ COUNTER_RESET_NEVER
+ (integer)
+
+
+
+ The counter will never be reset.
+
+
+
+
+
+ COUNTER_RESET_PER_LOAD
+ (integer)
+
+
+
+ The counter will be reset on each invocation of PHP.
+
+
+
+
+
+ COUNTER_RESET_PER_REQUEST
+ (integer)
+
+
+
+ The counter will be reset on each request.
+
+
+
+
+
+
+
+ &reftitle.examples;
+
+
+ Basic interface
+
+
+ The basic interface provides three simple functions, illustrated here:
+
+
+
+ "counter"'s basic interface
+
+
+]]>
+
+
+ &example.outputs;
+
+
+
+
+ The basic interface also provides a number of INI settings, documented
+ below.
+
+
+
+
+ Extended interface
+
+
+ The extended interface provides a small suite of functions that allow the
+ user to define an arbitrary number of named counters with unique settings.
+ The basic interface can be used in parallel with the extended interface.
+
+
+
+ "counter"'s extended interface
+
+
+]]>
+
+
+ When run once, the above example outputs:
+
+
+
+
+ If run a second time within the same instance of PHP, it outputs:
+
+
+
+
+ If then run a third time in a different instance of
+ PHP, it outputs:
+
+
+
+
+
+
+
+ Objective interface
+
+
+ The objective interface provides an object-oriented way to access the
+ extended interfaces. The following example shows how the above one would be
+ implemented using the objective interface. The output of this example is
+ exactly the same, except that instead of printing "Not a valid counter!",
+ this will instead issue a PHP warning that the variable
+ $counter_three is not an object. This example shows that
+ it is possible to subclass the Counter class defined
+ by the extension, as well as that the counter's value is maintained using
+ an instance variable rather than method access.
+
+
+
+ "counter"'s objective interface
+
+
+getMeta(COUNTER_META_NAME),
+ $this->getMeta(COUNTER_META_IS_PERSISTENT) ? '' : ' not',
+ $this->value);
+ }
+}
+
+if (($counter_one = Counter::getNamed("one")) === NULL) {
+ $counter_one = new Counter("one", 0, COUNTER_FLAG_PERSIST);
+}
+$counter_one->bumpValue(2); // we aren't allowed to "set" the value directly
+$counter_two = new Counter("two", 5);
+$counter_three = Counter::getNamed("three");
+$counter_four = new Counter("four", 2, COUNTER_FLAG_PERSIST | COUNTER_FLAG_SAVE | COUNTER_FLAG_NO_OVERWRITE);
+$counter_four->bumpValue(1);
+
+$counter_one->printCounterInfo();
+$counter_two->printCounterInfo();
+$counter_three->printCounterInfo();
+$counter_four->printCounterInfo();
+?>
+]]>
+
+
+
+
+
+
+
+ The Counter class
+ Counter
+
+
+
+ &reftitle.intro;
+
+ Represents a single counter object.
+
+
+
+
+ &reftitle.classsynopsis;
+
+
+ Counter
+
+
+ Counter
+
+
+
+
+
+
+
+
+
+
+ Counter::__construct
+
+ Creates an instance of a Counter which maintains a single numeric value.
+
+
+
+ &reftitle.description;
+
+ Counter::__construct
+ stringname
+ integerinitial_value
+ integerflags
+
+
+ Creates an instance of a Counter which maintains a single numeric value.
+
+
+
+ &reftitle.parameters;
+
+
+ name
+
+
+ The new counter's name.
+
+
+
+
+ initial_value
+
+
+ The initial value of the counter. Defaults to zero (0).
+
+
+
+
+ flags
+
+
+ Flags for the new counter, chosen from the
+ COUNTER_FLAG_* constants.
+
+
+
+
+
+
+ &reftitle.returnvalues;
+
+ Returns a Counter object on success.
+
+
+
+ &reftitle.errors;
+
+ Counter::__construct throws an Exception if something
+ goes wrong.
+
+
+
+
+
+
+ Counter::getValue
+
+ Get the current value of a counter.
+
+
+
+ &reftitle.description;
+
+ integerCounter::getValue
+
+
+
+ Counter::getValue returns the current value of a
+ counter.
+
+
+
+ &reftitle.returnvalues;
+
+ Counter::getValue returns an integer.
+
+
+
+ &reftitle.seealso;
+
+ Counter::bumpValue
+ Counter::resetValue
+
+
+
+
+
+
+ Counter::bumpValue
+
+ Change the current value of a counter.
+
+
+
+ &reftitle.description;
+
+ voidCounter::bumpValue
+ integeroffset
+
+
+ Counter::bumpValue updates the current value of a
+ counter.
+
+
+
+ &reftitle.parameters;
+
+
+ offset
+
+
+ The amount by which to change the counter's value. Can be negative.
+
+
+
+
+
+
+ &reftitle.seealso;
+
+ Counter::getValue
+ Counter::resetValue
+
+
+
+
+
+
+ Counter::resetValue
+
+ Reset the current value of a counter.
+
+
+
+ &reftitle.description;
+
+ voidCounter::resetValue
+
+
+
+ Counter::resetValue resets the current value of a
+ counter to its original initial value.
+
+
+
+ &reftitle.seealso;
+
+ Counter::getValue
+ Counter::bumpValue
+
+
+
+
+
+
+ Counter::getMeta
+
+ Return a piece of metainformation about a counter.
+
+
+
+ &reftitle.description;
+
+ mixedCounter::getMeta
+ integerattribute
+
+
+ Counter::getMeta returns metainformation about a
+ counter.
+
+
+
+ &reftitle.parameters;
+
+
+ attribute
+
+
+ The metainformation to retrieve.
+
+
+
+
+
+
+ &reftitle.returnvalues;
+
+ Counter::getMeta returns values of varying types
+ based on which metainformation was requested.
+
+
+
+
+
+
+ Counter::getNamed
+
+ Retrieve an existing named counter.
+
+
+
+ &reftitle.description;
+
+ CounterCounter::getNamed
+ stringname
+
+
+ Counter::getNamed returns an existing counter by name
+ if that name exists, or &null; otherwise. This is a static function.
+
+
+
+ &reftitle.parameters;
+
+
+ name
+
+
+ The counter name to search for.
+
+
+
+
+
+
+ &reftitle.returnvalues;
+
+ Counter::getNamed returns an existing counter by name
+ if that name exists, or &null; otherwise.
+
+
+
+
+
+
+
+
+
diff --git a/internals2/intro.xml b/internals2/intro.xml
index 5c2eb31583..7b3a7c791c 100644
--- a/internals2/intro.xml
+++ b/internals2/intro.xml
@@ -1,5 +1,5 @@
-
+
-
-
+
+ Preface
+
+
The Zend API has evolved considerably over time, as PHP has become a more
robust and widespread language. With the introduction of PHP 5 came the
Zend Engine 2 (ZE2). ZE2 came with an almost entirely new Object-Oriented
@@ -27,31 +29,31 @@
API. PHP 6, which is still under active development at the time of this
writing, introduces the Zend Engine 3 (ZE3), which brings full Unicode
support to the language.
-
+
-
+
This documentation is still under heavy development. The original Zend
documentation is preserved in its entirety in the
Zend Engine 1 section for those who
need it before this documentation is completed.
-
+
-
+
This section of the manual is devoted to ZE2. While PHP 4.3 is still in
widespread use, the differences in how extensions are written in ZE1 are
small; a short reference to them is given in an appendix to this section.
ZE3's API may yet change significantly, and is covered in another appendix.
It will be more fully documented when PHP 6 enters a beta testing stage.
-
+
-
+
The documentation in this section is current as of PHP 5.2.3, the most
recent stable release at the time of this writing. Notable differences in
the minor PHP 5 releases (5.0, 5.1, and 5.2) are given as appropriate.
-
-
+
+