Add mandatory PHPUnit CI workflow and GitHub FUNDING.yml

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+github: dacoto
+buy_me_a_coffee: dacoto
+custom: ["https://www.paypal.com/donate/?hosted_button_id=SGZ2VZ52ZD378"]

.github/workflows/generate.yml

@@ -0,0 +1,68 @@
+name: Regenerate PHP Classes
+
+on:
+  # Run manually from the Actions tab
+  workflow_dispatch:
+    inputs:
+      protoc_version:
+        description: 'Override protoc version (e.g. 34.1). Leave empty to derive from composer.json.'
+        required: false
+        default: ''
+
+  # Run automatically when the google/protobuf version in composer.json changes
+  push:
+    branches:
+      - main
+    paths:
+      - 'composer.json'
+      - 'gtfs-realtime.proto'
+
+jobs:
+  generate:
+    name: Generate PHP classes from proto
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          tools: composer
+
+      - name: Install Composer dependencies
+        run: composer install --no-interaction --prefer-dist
+
+      - name: Run generation script
+        run: |
+          chmod +x bin/generate.sh
+          if [[ -n "${{ github.event.inputs.protoc_version }}" ]]; then
+            bash bin/generate.sh --protoc-version "${{ github.event.inputs.protoc_version }}"
+          else
+            bash bin/generate.sh
+          fi
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet && git diff --cached --quiet; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit and push regenerated files
+        if: steps.changes.outputs.changed == 'true'
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add src/
+          # Include the version of protoc used in the commit message
+          PROTOC_VERSION=$(grep -oP '"google/protobuf":\s*"\K[^"]+' composer.json || echo "unknown")
+          git commit -m "chore: regenerate PHP classes (google/protobuf ${PROTOC_VERSION})"
+          git push

.github/workflows/tests.yml

@@ -0,0 +1,42 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - master
+      - main
+  pull_request:
+    branches:
+      - master
+      - main
+
+jobs:
+  tests:
+    name: PHPUnit (PHP ${{ matrix.php }})
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php:
+          - '8.4'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up PHP ${{ matrix.php }}
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          tools: composer
+          coverage: none
+
+      - name: Install Composer dependencies
+        run: composer install --no-interaction --prefer-dist --no-progress
+
+      - name: Run PHPUnit tests
+        run: vendor/bin/phpunit

.gitignore

@@ -0,0 +1,4 @@
+vendor/
+composer.lock
+examples/feed.pb
+.phpunit.result.cache

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dacoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1 +1,147 @@
-# gtfs-rt-php
+# gtfs-rt-php
+
+GTFS-Realtime library for PHP 8.4+ based on Google's [Protocol Buffers](https://github.com/protocolbuffers/protobuf) v5.
+
+A modern PHP implementation of the [GTFS Realtime](https://gtfs.org/documentation/realtime/reference/) specification.
+The proto definition was downloaded from [gtfs.org](https://gtfs.org/documentation/realtime/gtfs-realtime.proto) and converted to proto3 syntax for compatibility with the latest `google/protobuf` PHP library.
+
+## Requirements
+
+- PHP >= 8.4
+- [google/protobuf](https://packagist.org/packages/google/protobuf) ^5.34
+
+## Installation
+
+```bash
+composer require dacoto/gtfs-rt-php
+```
+
+## Usage
+
+### Creating a Feed Message
+
+```php
+use Google\Transit\Realtime\FeedMessage;
+use Google\Transit\Realtime\FeedHeader;
+use Google\Transit\Realtime\FeedHeader\Incrementality;
+use Google\Transit\Realtime\FeedEntity;
+use Google\Transit\Realtime\TripUpdate;
+use Google\Transit\Realtime\TripUpdate\StopTimeUpdate;
+use Google\Transit\Realtime\TripUpdate\StopTimeEvent;
+use Google\Transit\Realtime\TripDescriptor;
+
+$feedMessage = new FeedMessage();
+
+$header = new FeedHeader();
+$header->setGtfsRealtimeVersion('2.0');
+$header->setIncrementality(Incrementality::FULL_DATASET);
+$header->setTimestamp(time());
+$feedMessage->setHeader($header);
+
+$entity = new FeedEntity();
+$entity->setId('entity-1');
+
+$tripDescriptor = new TripDescriptor();
+$tripDescriptor->setTripId('trip-123');
+$tripDescriptor->setRouteId('route-42');
+
+$arrivalEvent = new StopTimeEvent();
+$arrivalEvent->setDelay(120); // 2 minutes late
+
+$stopTimeUpdate = new StopTimeUpdate();
+$stopTimeUpdate->setStopSequence(1);
+$stopTimeUpdate->setStopId('stop-A');
+$stopTimeUpdate->setArrival($arrivalEvent);
+
+$tripUpdate = new TripUpdate();
+$tripUpdate->setTrip($tripDescriptor);
+$tripUpdate->setStopTimeUpdate([$stopTimeUpdate]);
+
+$entity->setTripUpdate($tripUpdate);
+$feedMessage->setEntity([$entity]);
+
+// Serialize to binary protobuf
+$binaryData = $feedMessage->serializeToString();
+```
+
+### Parsing a Feed Message
+
+```php
+use Google\Transit\Realtime\FeedMessage;
+
+$binaryData = file_get_contents('https://your-agency.com/gtfs-rt/tripupdates.pb');
+
+$feedMessage = new FeedMessage();
+$feedMessage->mergeFromString($binaryData);
+
+echo "GTFS-RT version: " . $feedMessage->getHeader()->getGtfsRealtimeVersion() . PHP_EOL;
+
+foreach ($feedMessage->getEntity() as $entity) {
+    if ($entity->hasTripUpdate()) {
+        $tripUpdate = $entity->getTripUpdate();
+        echo "Trip ID: " . $tripUpdate->getTrip()->getTripId() . PHP_EOL;
+
+        foreach ($tripUpdate->getStopTimeUpdate() as $stu) {
+            if ($stu->hasArrival()) {
+                echo "  Stop " . $stu->getStopId() . " delay: " . $stu->getArrival()->getDelay() . "s" . PHP_EOL;
+            }
+        }
+    }
+}
+```
+
+See full examples in the [examples/](examples/) directory.
+
+## Proto3 Conversion Notes
+
+The official GTFS Realtime proto uses `proto2` syntax. This library converts it to `proto3` to be compatible with the latest `google/protobuf` PHP library. The key changes are:
+
+1. Changed `syntax = "proto2"` to `syntax = "proto3"`
+2. Removed all `optional` and `required` field labels (all fields are optional in proto3)
+3. Removed all `extensions` ranges (not supported in proto3)
+4. Removed all explicit `[default = ...]` values
+5. Added `UNKNOWN_CAUSE = 0`, `NO_SERVICE = 0`, and `UNKNOWN_SEVERITY = 0` as first enum values (proto3 requires first value to be 0)
+6. Added PHP namespace options: `php_namespace` and `php_metadata_namespace`
+
+## Running Tests
+
+```bash
+composer install
+vendor/bin/phpunit
+```
+
+## Regenerating PHP Classes
+
+The PHP classes in `src/` are generated automatically from `gtfs-realtime.proto` using `protoc`.
+
+### Automatic (GitHub Actions)
+
+Every time `composer.json` or `gtfs-realtime.proto` is changed on `main`, the
+[Regenerate PHP Classes](.github/workflows/generate.yml) workflow runs automatically,
+downloads the correct `protoc` binary, regenerates all PHP classes, and commits the result.
+
+You can also trigger it manually from the **Actions** tab, optionally overriding the `protoc` version.
+
+### Manual (local)
+
+Run the generation script — it resolves the `protoc` version from `composer.json` (or `composer.lock`) automatically:
+
+```bash
+bash bin/generate.sh
+```
+
+Or override the protoc version explicitly:
+
+```bash
+bash bin/generate.sh --protoc-version 34.1
+```
+
+The script:
+1. Reads the `google/protobuf` version from `composer.lock` (or `composer.json`)
+2. Derives the matching `protoc` release (e.g. PHP `v5.34.1` → `protoc v34.1`)
+3. Downloads the `protoc` binary from [github.com/protocolbuffers/protobuf](https://github.com/protocolbuffers/protobuf/releases)
+4. Regenerates all PHP classes in `src/` from `gtfs-realtime.proto`
+
+## License
+
+MIT — See [LICENSE](LICENSE)