Add PIE extension support via separate repository

- Update release.sh to automate extension repo releases
  - Clone extension repo to .ext directory
  - Update submodule reference after main release
  - Create matching release in extension repo
  - Include safety checks and error handling
  - Create php_maxminddb-{version}-src.tgz from submodule ext/ directory
  - Upload as GitHub release asset
- Update README.md to promote PIE as recommended installation method
- Add maxmind-db/reader-ext to composer.json suggest section
- Add .ext to .gitignore
- Document implementation plan in plan.md

References:
- php/pie#39

Author: oschwald

.gitignore

@@ -6,6 +6,7 @@
 *.sublime-*
 *.sw?
 .deps
+.ext
 .gh-pages
 /.idea
 /.php-cs-fixer.cache

README.md

@@ -5,9 +5,25 @@
 This is the PHP API for reading MaxMind DB files. MaxMind DB is a binary file
 format that stores data indexed by IP address subnets (IPv4 or IPv6).
 
-## Installation (Composer) ##
+## Installation ##
 
-We recommend installing this package with [Composer](https://getcomposer.org/).
+### C Extension (Recommended for Performance) ###
+
+For significantly faster IP lookups, we recommend installing the C extension via
+[PIE](https://github.com/php/pie):
+
+```bash
+pie install maxmind-db/reader-ext
+```
+
+The C extension requires the [libmaxminddb](https://github.com/maxmind/libmaxminddb)
+C library. See the [installation instructions](https://github.com/maxmind/MaxMind-DB-Reader-php-ext#prerequisites)
+for your platform.
+
+### Pure PHP (No Compilation Required) ###
+
+If you prefer not to compile a C extension or need maximum portability, you can
+install the pure PHP implementation with [Composer](https://getcomposer.org/).
 
 ### Download Composer ###
 
@@ -108,18 +124,31 @@ MaxMind provides an optional C extension that is a drop-in replacement for
 Reader API as described above and install the extension as described below. If
 you are using an autoloader, no changes to your code should be necessary.
 
-### Installing Extension ###
+### Installing Extension via PIE (Recommended) ###
+
+We recommend installing the extension via [PIE](https://github.com/php/pie):
+
+```bash
+pie install maxmind-db/reader-ext
+```
+
+See the [extension repository](https://github.com/maxmind/MaxMind-DB-Reader-php-ext#prerequisites)
+for prerequisites including libmaxminddb installation instructions.
+
+### Installing Extension via PECL (Legacy) ###
 
 First install [libmaxminddb](https://github.com/maxmind/libmaxminddb) as
 described in its [README.md
 file](https://github.com/maxmind/libmaxminddb/blob/main/README.md#installing-from-a-tarball).
 After successfully installing libmaxmindb, you may install the extension
-from [pecl](https://pecl.php.net/package/maxminddb):
+from [PECL](https://pecl.php.net/package/maxminddb):
 
 ```
 pecl install maxminddb
 ```
 
+### Installing Extension from Source ###
+
 Alternatively, you may install it from the source. To do so, run the following
 commands from the top-level directory of this distribution:
 

composer.json

@@ -18,7 +18,8 @@
     "suggest": {
         "ext-bcmath": "bcmath or gmp is required for decoding larger integers with the pure PHP decoder",
         "ext-gmp": "bcmath or gmp is required for decoding larger integers with the pure PHP decoder",
-        "ext-maxminddb": "A C-based database decoder that provides significantly faster lookups"
+        "ext-maxminddb": "A C-based database decoder that provides significantly faster lookups",
+        "maxmind-db/reader-ext": "C extension for significantly faster IP lookups (install via PIE: pie install maxmind-db/reader-ext)"
     },
     "conflict": {
         "ext-maxminddb": "<1.11.1 || >=2.0.0"

dev-bin/release.sh

@@ -70,6 +70,8 @@ echo "$notes"
 
 pecl package
 
+package="maxminddb-$version.tgz"
+
 read -p "Push to origin? (y/n) " should_push
 
 if [ "$should_push" != "y" ]; then
@@ -83,4 +85,157 @@ git push
 
 gh release create --target "$(git branch --show-current)" -t "$version" -n "$notes" "$tag"
 
-echo "Upload PECL package to pecl.php.net!"
+# =============================================================================
+# EXTENSION REPOSITORY RELEASE AUTOMATION
+# =============================================================================
+
+ext_repo_dir=".ext"
+ext_repo_url="[email protected]:maxmind/MaxMind-DB-Reader-php-ext.git"
+
+echo ""
+echo "==================================================================="
+echo "UPDATING EXTENSION REPOSITORY"
+echo "==================================================================="
+
+# Check if extension repository exists locally
+if [ ! -d "$ext_repo_dir" ]; then
+    echo "Extension repository not found at: $ext_repo_dir"
+    echo "Cloning extension repository..."
+    git clone --recurse-submodules "$ext_repo_url" "$ext_repo_dir"
+
+    if [ $? -ne 0 ]; then
+        echo "ERROR: Failed to clone extension repository"
+        echo "Please clone manually: git clone --recurse-submodules $ext_repo_url $ext_repo_dir"
+        exit 1
+    fi
+fi
+
+# Navigate to extension repository
+pushd "$ext_repo_dir" > /dev/null
+
+# Safety check: ensure working directory is clean
+if [ -n "$(git status --porcelain)" ]; then
+    echo "ERROR: Extension repository has uncommitted changes"
+    echo "Please commit or stash changes in: $ext_repo_dir"
+    popd > /dev/null
+    exit 1
+fi
+
+# Ensure we're on main branch
+current_branch=$(git rev-parse --abbrev-ref HEAD)
+if [ "$current_branch" != "main" ]; then
+    echo "Switching to main branch..."
+    git checkout main
+fi
+
+# Pull latest changes
+echo "Pulling latest changes from origin..."
+git pull origin main
+
+# Update submodule to the new tag
+echo "Updating submodule to $tag..."
+cd MaxMind-DB-Reader-php
+git fetch --tags origin
+git checkout "$tag"
+
+if [ $? -ne 0 ]; then
+    echo "ERROR: Failed to checkout tag $tag in submodule"
+    popd > /dev/null
+    exit 1
+fi
+
+cd ..
+
+# Stage submodule update
+git add MaxMind-DB-Reader-php
+
+# Check if there are actual changes
+if [ -z "$(git status --porcelain)" ]; then
+    echo "No changes needed in extension repository (already at $tag)"
+    popd > /dev/null
+    echo "Extension repository is up to date"
+else
+    # Commit submodule update
+    echo "Committing submodule update..."
+    git commit -m "Update to MaxMind-DB-Reader-php $version
+
+This updates the submodule reference to track the $tag release.
+
+Release notes from main repository:
+$notes"
+
+    # Push changes
+    echo "Pushing to origin..."
+    git push origin main
+
+    if [ $? -ne 0 ]; then
+        echo "ERROR: Failed to push to extension repository"
+        popd > /dev/null
+        exit 1
+    fi
+
+    # Create pre-packaged source tarball for PIE
+    # PIE needs this because it doesn't handle git submodules automatically
+    echo "Creating pre-packaged source tarball for PIE..."
+    pie_tarball="maxminddb-${tag}.tgz"
+
+    # Create tarball with files at root level (PIE requirement)
+    # Note: naming must be {extension-name}-v{version}.tgz
+    pushd MaxMind-DB-Reader-php/ext > /dev/null
+    tar -czf "../../$pie_tarball" *
+    popd > /dev/null
+
+    if [ ! -f "$pie_tarball" ]; then
+        echo "ERROR: Failed to create source tarball"
+        popd > /dev/null
+        exit 1
+    fi
+
+    echo "Created $pie_tarball"
+
+    # Create corresponding release in extension repo with same tag
+    echo "Creating release $tag in extension repository..."
+    gh release create "$tag" \
+        --repo maxmind/MaxMind-DB-Reader-php-ext \
+        --title "$version" \
+        --notes "Extension release for MaxMind-DB-Reader-php $version
+
+This release tracks the $tag tag of the main repository.
+
+## Release notes from main repository
+
+$notes" \
+        "$pie_tarball"
+
+    if [ $? -ne 0 ]; then
+        echo "ERROR: Failed to create release in extension repository"
+        echo "You may need to create it manually at:"
+        echo "https://github.com/maxmind/MaxMind-DB-Reader-php-ext/releases/new?tag=$tag"
+        popd > /dev/null
+        exit 1
+    fi
+
+    # Clean up tarball
+    rm -f "$pie_tarball"
+
+    echo ""
+    echo "✓ Extension repository updated successfully!"
+    echo "✓ Release created: https://github.com/maxmind/MaxMind-DB-Reader-php-ext/releases/tag/$tag"
+    echo "✓ Pre-packaged source uploaded: $pie_tarball"
+fi
+
+popd > /dev/null
+
+echo ""
+echo "==================================================================="
+echo "RELEASE COMPLETE"
+echo "==================================================================="
+echo ""
+echo "Main repository: https://github.com/maxmind/MaxMind-DB-Reader-php/releases/tag/$tag"
+echo "Extension repository: https://github.com/maxmind/MaxMind-DB-Reader-php-ext/releases/tag/$tag"
+echo ""
+echo "Action items:"
+echo "1. Upload PECL package to pecl.php.net: https://pecl.php.net/package-new.php"
+echo "   File: $package"
+echo "2. Verify PIE installation: pie install maxmind-db/reader-ext:^$version"
+echo "3. Announce release"