php · NickSdot · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026
@@ -20,8 +20,6 @@ jobs:
         uses: actions/checkout@v6
       - name: Install dependencies
         run: pip install -r docs/requirements.txt
-      - name: Check formatting
-        run: make -C docs check-formatting
       - name: Publish
         if: github.event_name == 'push'
         uses: sphinx-notes/pages@v3

diff --git a/docs/Makefile b/docs/Makefile
@@ -7,30 +7,16 @@ SPHINXBUILD ?= sphinx-build
 
 SOURCEDIR = source
 BUILDDIR = build
-RSTFMT = rstfmt
-RSTFMTFLAGS = -w 100
-
-rwildcard = $(foreach d,$(wildcard $(1:=/*)),$(call rwildcard,$d,$2) $(filter $(subst *,%,$2),$d))
-FILES = $(call rwildcard,$(SOURCEDIR),*.rst)
 
 all : html
 
-.PHONY : check-formatting clean html preflight
+.PHONY : clean html
 .SUFFIXES : # Disable legacy behavior
 
-check-formatting :
-	$(RSTFMT) $(RSTFMTFLAGS) --check $(SOURCEDIR)
-
 clean :
-	rm -rf -- $(wildcard $(SOURCEDIR)/.~ $(BUILDDIR))
+	rm -rf -- $(BUILDDIR)
 
-html : preflight
+html :
 	$(SPHINXBUILD) -M $@ $(SOURCEDIR) $(BUILDDIR)
 	@printf 'Browse the \e]8;;%s\e\\%s\e]8;;\e\\.\n' \
 		"file://$(abspath $(BUILDDIR))/$@/index.$@" "php-src html docs locally"
-
-preflight : $(SOURCEDIR)/.~
-
-$(SOURCEDIR)/.~ : $(FILES)
-	$(RSTFMT) $(RSTFMTFLAGS) $?
-	touch $@
diff --git a/docs/README.md b/docs/README.md
@@ -27,12 +27,4 @@ your browser.
 
 ## Formatting
 
-The files in this documentation are formatted using the
-[``rstfmt``](https://github.com/dzhu/rstfmt) tool.
-
-```bash
-rstfmt -w 100 source
-```
-
-This tool is not perfect. It breaks on custom directives, so we might switch to
-either a fork or something else in the future.
+Formatting is temporarily not enforced during the Markdown migration.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,4 +1,4 @@
 Sphinx
+myst-parser>=5.1
 sphinx-design
 sphinxawesome-theme
-rstfmt
diff --git a/docs/source/_templates/redirect.html b/docs/source/_templates/redirect.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url={{ redirect_url }}">
+    <link rel="canonical" href="{{ redirect_url }}">
+    <title>Redirecting&hellip;</title>
+    <script>
+      window.location.replace({{ redirect_url | tojson }} + window.location.hash);
+    </script>
+  </head>
+  <body>
+    <p>This page has moved to <a href="{{ redirect_url }}">its new location</a>.</p>
+  </body>
+</html>
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -15,9 +15,18 @@
 project = 'php-src docs'
 author = 'The PHP Group'
 extensions = [
+    'myst_parser',
     'sphinx_design',
     'sphinx.ext.autosectionlabel',
 ]
+exclude_patterns = ['**/*TODO.md']
+myst_enable_extensions = [
+    'alert',
+    'gfm_autolink',
+    'strikethrough',
+    'tasklist',
+]
+myst_heading_anchors = 6
 templates_path = ['_templates']
 html_theme = 'sphinxawesome_theme'
 html_static_path = ['_static']
@@ -58,3 +67,17 @@
 )
 html_theme_options = asdict(theme_options)
 pygments_style = 'sphinx'
+
+
+redirects = {
+    'core/data-structures/reference-counting': '../memory-management/reference-counting.html',
+}
+
+
+def generate_redirects(_app):
+    for source, target in redirects.items():
+        yield source, {'redirect_url': target}, 'redirect.html'
+
+
+def setup(app):
+    app.connect('html-collect-pages', generate_redirects)
diff --git a/docs/source/core/TODO.md b/docs/source/core/TODO.md
@@ -0,0 +1,8 @@
+Core TODO
+
+Pages to add:
+
+- Parser and AST: grammar generation, AST representation, compilation boundaries,
+  and important extension points.
+- Virtual Machine: opcode execution, operands, call frames, and VM variants.
+- Object Handlers: handler contracts, object storage, and common ownership traps.
diff --git a/docs/source/core/data-structures/TODO.md b/docs/source/core/data-structures/TODO.md
@@ -0,0 +1,4 @@
+Data Structures TODO
+
+- Add a HashTable page covering ownership, iteration, mutation, and common APIs.
+- Expand the zval macro table and document the remaining internal zval types.
diff --git a/docs/source/core/data-structures/index.md b/docs/source/core/data-structures/index.md
@@ -0,0 +1,11 @@
+# Data Structures
+
+```{toctree}
+   :hidden:
+
+zval
+zend_string
+zend_constant
+```
+
+This section provides an overview of the core data structures used in php-src.
diff --git a/docs/source/core/data-structures/index.rst b/docs/source/core/data-structures/index.rst
diff --git a/docs/source/core/data-structures/zend_constant.md b/docs/source/core/data-structures/zend_constant.md
@@ -0,0 +1,65 @@
+# zend_constant
+
+PHP constants (referring to non-class constants) are stored in a dedicated structure
+`zend_constant`, which holds both the value of the constant and details for using it.
+
+## definition
+
+```c
+
+   typedef struct _zend_constant {
+       zval value;
+       zend_string *name;
+       zend_string *filename;
+       HashTable *attributes;
+   } zend_constant;
+```
+
+The `value` field stores both the value itself and some metadata. The `name` and `filename`
+store the name of the constant and the name of the file in which it was defined. The `attributes`
+field stores the attributes applied to the constant.
+
+## value
+
+The value of the constant is stored in the {doc}`./zval` `value`. However, since the `zval`
+structure has extra space, for constants this is used to store both the number of the module that
+the constant was defined in, and a combination of the flags that affect the usage of the constant.
+
+This extra information is placed in the `uint32_t` field `value.u2.constant_flags`.
+
+The bottom 16 bits are used to hold flags about the constant
+
+```c
+
+   #define CONST_PERSISTENT     (1<<0) /* Persistent */
+   #define CONST_NO_FILE_CACHE  (1<<1) /* Can't be saved in file cache */
+   #define CONST_DEPRECATED     (1<<2) /* Deprecated */
+   #define CONST_OWNED          (1<<3) /* constant should be destroyed together
+                                            with class */
+```
+
+These bottom 16 bits can be accessed with the `ZEND_CONSTANT_FLAGS()` macro, which is given a
+`zend_constant` pointer as a parameter.
+
+On the other hand, the top 16 bits are used to store the number of the PHP module that registered
+the constant. For constants defined by the user, the module number stored will be
+`PHP_USER_CONSTANT`. This module number can be accessed with the `ZEND_CONSTANT_MODULE_NUMBER()`
+macro, which is likewise given a `zend_constant` pointer as a parameter.
+
+## name
+
+The `name` holds a {doc}`zend_string` with the name of the constant, to allow searching for
+constants that have already been defined. This string is released when the constant itself is freed.
+
+## filename
+
+The `filename` holds another `zend_string` with the name of the file in which the constant was
+defined, or `NULL` if not defined userland code. This field provides the foundation for the PHP
+method `ReflectionConstant::getFileName()`.
+
+## attributes
+
+The `attributes` holds a `HashTable` (essentially an array) with the details of the attributes
+that were applied to the constant. Note that attributes can only be added to constants declared at
+compile time via `const`, e.g. `const EXAMPLE = 123`, not those declared at runtime, e.g.
+`define( 'EXAMPLE', 123 );`.
diff --git a/docs/source/core/data-structures/zend_constant.rst b/docs/source/core/data-structures/zend_constant.rst