Refactor Examples

.github/workflows/examples.yml

@@ -0,0 +1,39 @@
+name: Examples
+
+on:
+  schedule:
+    # Weekly, on Monday morning.
+    - cron: "0 7 * * 1"
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - 'examples/**'
+      - 'tests/QueryPath/ExampleRunner.php'
+      - 'tests/run-examples.php'
+      - '.github/workflows/examples.yml'
+
+jobs:
+  network:
+    name: Network examples
+    runs-on: ubuntu-latest
+
+    # These call third-party services, so they can fail for reasons that have
+    # nothing to do with a change here. The examples retry when an API asks them
+    # to slow down; anything that still fails is treated as a real problem.
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          ini-values: error_reporting=E_ALL
+          extensions: dom, simplexml, zip, curl
+
+      - name: Install Composer Dependencies
+        uses: ramsey/composer-install@v4
+
+      - name: Run the examples that call remote services
+        run: composer run test:examples:network

.github/workflows/unit-testing.yml

@@ -22,6 +22,8 @@ jobs:
         with:
           php-version: ${{ matrix.php-versions }}
           ini-values: error_reporting=E_ALL
+          # zip is needed by the .docx and .odt examples, which ExamplesTest runs.
+          extensions: dom, simplexml, zip
 
       - name: Install Composer Dependencies
         uses: ramsey/composer-install@v4

.gitignore

@@ -15,3 +15,4 @@ vendor/
 composer.lock
 .phpunit.result.cache
 .idea/
+.DS_Store

CHANGELOG.md

@@ -3,7 +3,15 @@ QueryPath Changelog
 
 # Unreleased changes
 
--
+- Reorganise, modernise, and repair the `examples/` directory. Each example now lives in its own subdirectory with an `index.php`, and the full set is indexed in `examples/quickstart-guide.md`
+- Convert the remaining legacy examples: `simple_example.php`, `techniques.php`, `svg.php`, `rss.php`, `odt.php`, `parse_php.php`, and `sparql.php`
+- Fix examples that no longer ran: send a `User-Agent` where remote hosts now require one, resolve paths relative to the example rather than the working directory, and stop relying on the removed `qp.php` autoloader and the PHP 8 incompatible `eachLambda()`
+- Rewrite `examples/quickstart-guide.md`, which documented an autoloader and a set of Composer caveats that no longer apply
+- Remove unused example fixtures (`The_Beatles.rdf`, `testGrid.html`, `out.svg`) and generated output
+- Add `ext-dom` and `ext-simplexml` to the `composer.json` requirements, and `ext-zip` to the dev requirements
+- Add `QueryPathTests\ExamplesTest`, which runs every offline example on each supported PHP version and fails if one stops working. The examples that call third-party services are run by the new `Examples` workflow, weekly and whenever an example changes
+- Rewrite the cURL example against the PubMed E-utilities API. MusicBrainz throttles by IP address, which made the example unusable from any shared address
+- Add `composer run test:examples` (and `test:examples:network`) to run the examples locally
 
 # 4.1.0
 

composer.json

@@ -24,7 +24,9 @@
   ],
   "require": {
     "php": "^7.1 || ~8.0.0 || ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0",
-    "masterminds/html5": "^2.0"
+    "masterminds/html5": "^2.0",
+    "ext-dom": "*",
+    "ext-simplexml": "*"
   },
   "autoload": {
     "psr-4": {
@@ -36,6 +38,7 @@
     ]
   },
   "require-dev": {
+    "ext-zip": "*",
     "mockery/mockery": "^1.1",
     "yoast/phpunit-polyfills": "^1.0",
     "dealerdirect/phpcodesniffer-composer-installer": "^0.7.0",
@@ -49,7 +52,10 @@
   "scripts": {
     "lint": "@php ./vendor/squizlabs/php_codesniffer/bin/phpcs",
     "lint:fix": "@php ./vendor/squizlabs/php_codesniffer/bin/phpcbf",
-    "lint:min-php": "@lint --standard=phpcompat.xml"
+    "lint:min-php": "@lint --standard=phpcompat.xml",
+    "test": "@php ./vendor/bin/phpunit",
+    "test:examples": "@php ./tests/run-examples.php --all",
+    "test:examples:network": "@php ./tests/run-examples.php --network"
   },
   "replace": {
     "arthurkushman/query-path": "3.1.4",

examples/README.md

@@ -0,0 +1,35 @@
+# QueryPath Examples
+
+Runnable examples covering the QueryPath API. Each one lives in its own directory
+with an `index.php` you can run directly:
+
+```bash
+composer install
+php examples/hello-world/index.php
+```
+
+Most of them print HTML, so they also work if you point a web server at this
+directory:
+
+```bash
+php -S localhost:8000 -t examples
+```
+
+**[Read the QuickStart guide](quickstart-guide.md)** — it introduces the library
+and indexes every example in this directory with a note on what each one covers.
+
+New to QueryPath? Start with [hello-world](hello-world/index.php).
+
+## Checking they all still work
+
+The offline examples are part of the unit test suite, so they run on every pull
+request across all supported PHP versions. To run the whole set — including the
+ones that call third-party services — by hand:
+
+```bash
+composer run test:examples           # all of them
+composer run test:examples:network   # only the ones that need a remote service
+```
+
+An example passes if it exits cleanly, emits no PHP diagnostic, and produces a
+reasonable amount of output.