docs: performance page measured on the dedicated server, PHP 8.5

- list page is about 0.01 ms per 25 rows on current PHP, not 0.002 ms; the old figure came from a laptop on PHP 8.1, where a slower htmlspecialchars() hid more of the construction cost
- detail page is nearly 2x faster than plain arrays; memory is under 300 bytes per row
- names the server and PHP version, and says why the gap narrows on older PHP
- benchmark command drops the -n form, which fails on builds that load opcache from php.ini

Author: daveedis

README.md

@@ -64,7 +64,7 @@ Full guides and references ([browse on GitHub](https://github.com/interactivetoo
 - **Lookup**
     - [Method Reference](docs/method-reference.md) - every method, grouped by what it returns
     - [Troubleshooting](docs/troubleshooting.md) - common error messages and gotchas, with fixes
-    - [Performance](docs/performance.md) - what SmartArray costs vs plain arrays: about 0.002 ms per 25-row page and 300 bytes per row
+    - [Performance](docs/performance.md) - what SmartArray costs vs plain arrays: about 0.01 ms per 25-row page and under 300 bytes per row
     - [AI Reference](docs/ai-reference.md) - the complete API in one dense file, written for AI coding assistants
 
 ## You're Never Locked In

docs/performance.md

@@ -1,11 +1,11 @@
 # Performance: What SmartArray Costs vs Plain Arrays
 
 At worst, wrapping a 25-row query
-result and rendering it costs about 2 microseconds (0.002 ms) more than the
+result and rendering it costs about 10 microseconds (0.00001 s) more than the
 same page written by hand with plain arrays and manual HTML encoding; at best
-it comes out ahead, because SmartString often encodes faster than PHP's
-built-in encoder (2.5x on the long-text detail page below). Memory
-overhead is about 300 bytes per row no matter how large the fields are.
+it comes out ahead, because SmartString encodes long text faster than PHP's
+built-in encoder (nearly 2x on the detail page below). Memory overhead is
+under 300 bytes per row no matter how large the fields are.
 
 All times on this page are in milliseconds (ms), thousandths of a second.
 For scale: response-time research puts the threshold where people start to
@@ -34,9 +34,9 @@ versions are verified to produce byte-identical HTML before timing:
 
 | Scenario                                       | Plain array | SmartArray | Difference         |
 |------------------------------------------------|-------------|------------|--------------------|
-| List page (25 rows, encoded title+summary)     | 0.0271 ms   | 0.0288 ms  | +0.0017 ms (1.06x) |
-| Detail page (1 row, encoded 5KB body)          | 0.0120 ms   | 0.0047 ms  | **2.5x faster**    |
-| Raw loop (plain SmartArray, create + 50 reads) | 0.0004 ms   | 0.0070 ms  | +0.0066 ms         |
+| List page (25 rows, encoded title+summary)     | 0.0213 ms   | 0.0309 ms  | +0.0096 ms (1.45x) |
+| Detail page (1 row, encoded 5KB body)          | 0.0094 ms   | 0.0050 ms  | **nearly 2x faster** |
+| Raw loop (plain SmartArray, create + 50 reads) | 0.0006 ms   | 0.0077 ms  | +0.0072 ms         |
 
 SmartArray times include constructing the object from the plain records
 array, the same work the database layer does when it returns results. The
@@ -45,18 +45,19 @@ output or encoding at all: it uses plain `SmartArray` (no HTML mode),
 where field reads return plain strings and no SmartString objects are
 created, so data-processing code skips the encoding layer entirely.
 
-**Encoding is not where the time goes.** Render the same pages with no
+**Construction is where the time goes.** Render the same pages with no
 encoding on either side (plain SmartArray against plain arrays echoed
-raw) and the list page still measures +0.0066 ms: the overhead is
-construction either way, and SmartString encodes as fast as or faster
-than hand-encoding, so HTML mode adds nothing on net.
+raw) and the list page still measures +0.007 ms. HTML mode adds about
+0.003 ms on top for the 50 SmartString objects, and on longer fields
+SmartString's faster encoding turns that around, which is why the detail
+page wins.
 
 To put the list-page row in perspective: to lose a single millisecond on
 one page load, your code would have to build and render that 25-row list
-about 600 times. Same math for the raw-loop row: wrapping one 25-row query
-result in a SmartArray and looping over it costs 0.0066 ms more than the
-plain array, so a single request would have to create 151 separate
-SmartArrays, 25 rows each, and loop over all of them - 3,775 rows - before
+about 100 times. Same math for the raw-loop row: wrapping one 25-row query
+result in a SmartArray and looping over it costs 0.0072 ms more than the
+plain array, so a single request would have to create about 140 separate
+SmartArrays, 25 rows each, and loop over all of them - 3,500 rows - before
 the total penalty reached one millisecond.
 
 **Why the detail page is faster.** SmartString checks whether text is
@@ -71,14 +72,14 @@ for the encoding measurements across platforms.
 
 | Data               | Payload size | SmartArray adds | Per record |
 |--------------------|--------------|-----------------|------------|
-| 25 news records    | ~133 KB      | +7.8 KB         | ~320 bytes |
-| 1,000 news records | ~5.2 MB      | +294 KB         | ~301 bytes |
+| 25 news records    | ~133 KB      | +6.4 KB         | ~260 bytes |
+| 1,000 news records | ~5.2 MB      | +247 KB         | ~250 bytes |
 
 Field values are never copied: PHP strings are reference-counted, so a 5KB
 content field is shared between the plain array and the SmartArray that
 wraps it. The per-record overhead is the row object itself, so the bytes
 per row are the constant, not a percentage: on these ~5 KB news records it
-works out to 6%, on records with a 50 KB body it would be 0.6%, and on
+works out to 5%, on records with a 50 KB body it would be 0.5%, and on
 lean three-column rows it could exceed 100% - while staying the same few
 hundred bytes each time.
 
@@ -98,12 +99,12 @@ nearly all of it; everything after is close to free:
 
 | Operation (25 rows, plain SmartArray) | Cost        |
 |---------------------------------------|-------------|
-| Construct from plain records array    | 0.0045 ms   |
-| Construct via `fromDatabaseRows()`    | 0.0037 ms   |
-| foreach over all rows                 | 0.0007 ms   |
-| Read a field (`$row->title`)          | 0.000046 ms |
-| `toArray()` on the record set         | 0.0006 ms   |
-| `toArray()` on one flat row           | 0.000027 ms |
+| Construct from plain records array    | 0.0043 ms   |
+| Construct via `fromDatabaseRows()`    | 0.0033 ms   |
+| foreach over all rows                 | 0.0008 ms   |
+| Read a field (`$row->title`)          | 0.000058 ms |
+| `toArray()` on the record set         | 0.0009 ms   |
+| `toArray()` on one flat row           | 0.000033 ms |
 
 ZenDB constructs its result sets with `fromDatabaseRows()`, the faster
 construct row above: database rows are uniform (same columns in every row,
@@ -125,18 +126,21 @@ Two things follow from construction being the whole cost:
 - **It's eager, per row fetched.** Query 500 rows to show 10 and you pay
   for 500. LIMIT in the query beats any amount of avoiding SmartArray.
 - **Hot loops: unwrap once.** A report loop touching every field thousands
-  of times can call `->toArray()` first (0.000027 ms on a flat row) and
+  of times can call `->toArray()` first (0.000033 ms on a flat row) and
   loop the plain array.
 
 ## Reproducing the Numbers
 
 Every number on this page comes from one script, which builds the test
 data, verifies both versions produce byte-identical HTML, and then times
-them. Local runs are direction checks; numbers move a few percent between
-runs and more between machines. Run with opcache on and xdebug off:
+them. The numbers above are from a dedicated Linux x64 server (Intel Xeon
+E-2386G) on PHP 8.5 with opcache on and JIT off. The list-page gap tracks
+how fast the platform's own `htmlspecialchars()` runs: on PHP 8.1, or on a
+laptop, the plain-array side is slower and the gap narrows. Run it on your
+own machine with opcache on and xdebug off:
 
 ```bash
-php -n -d zend_extension=opcache -d opcache.enable_cli=1 benchmarks/news-page.php
+php -d opcache.enable_cli=1 -d xdebug.mode=off benchmarks/news-page.php
 ```
 
 ---