README

Generated PHP bindings for the Nyx backup platform Protocol Buffers contract (backup.v1). The .proto source of truth is not copied here — it is pulled in as a git submodule from the upstream CS-Nyx2/protobuf module, and the PHP classes in src/ are generated from it.

This package exists so the Laravel API (and any other PHP consumer) can depend on the contract via Composer / Packagist instead of vendoring protoc output by hand.

Layout

protobuf-php/
├── protobuf/                 # git submodule -> CS-Nyx2/protobuf (the .proto contract)
├── src/                      # generated PHP (committed; PSR-4 root "CoolStudio\")
│   └── CoolStudio/Nyx/V1/... #   message + enum classes (CoolStudio\Nyx\V1\…)
│       └── Meta/...          #   descriptor metadata (CoolStudio\Nyx\V1\Meta\…)
├── buf.gen.yaml              # PHP-only codegen template (out: ./src)
├── scripts/generate.sh       # regenerate src/ (buf if present, else protoc)
├── Makefile                  # make generate / make check / make submodule
├── composer.json             # Packagist manifest (PSR-4 autoload)
└── .github/workflows/        # ci.yml + sync-protobuf.yml + tag-release.yml

The generated code is committed on purpose: Packagist installs straight from a git tag with no build step, so consumers must receive ready-to-autoload PHP.

How releases happen (automated)

You normally never touch this repo by hand. Contract changes flow through to a published Composer version end-to-end:

1. Upstream proto change. CS-Nyx2/protobuf validates a .proto change (buf lint/build/breaking) and, on success, sends a repository_dispatch (protobuf-updated) here.
2. Regenerate — sync-protobuf.yml pins the submodule to that validated commit, runs make generate, and commits the regenerated src/ (plus the bumped submodule pointer) straight to main.
3. Validate — ci.yml runs on the new main commit: composer validate --strict, a generated-code drift check, a PHP lint, and an autoload smoke test.
4. Tag — when CI succeeds, tag-release.yml fires (via workflow_run). If any *.php or composer.json changed since the last vX.Y.Z tag, it patch-bumps and pushes a new tag. Doc-only or CI-only pushes don't cut a release.
5. Publish — Packagist's own GitHub webhook sees the new tag and refreshes the package. Nothing in this repo pings the Packagist API; pushing the tag is the release.

So a validated upstream proto change becomes a new Composer version with no human in the loop. The manual steps below are escape hatches: local iteration, and cutting a minor/major version (the automation only ever patch-bumps).

Using the library (consumers)

composer require coolstudio/nyx-protobuf

use CoolStudio\Nyx\V1\BackupTask;
use CoolStudio\Nyx\V1\TaskStatus;

$task = new BackupTask();
$task->setStatus(TaskStatus::TASK_STATUS_PENDING);

The only runtime dependency is the official google/protobuf library. For better performance you may optionally install the native protobuf PECL extension; it is not required.

Regenerating the bindings by hand (maintainers)

In normal operation sync-protobuf.yml does this for you (see above). Do it locally only to iterate on the codegen template, debug drift, or recover if the automation is wedged. You can also trigger the same job from the GitHub Actions tab via Run workflow (Sync protobuf), optionally passing a specific proto commit SHA.

Prerequisites: protoc (or buf). PHP support is built into protoc, so no extra plugin is needed.

git submodule update --init --recursive   # or: make submodule
make generate                             # rewrites src/ from protobuf/proto

To advance to a newer version of the contract, move the submodule pointer and regenerate:

git -C protobuf pull origin main
make generate
git add protobuf src
git commit -m "chore: regenerate against protobuf <sha>"

CI (.github/workflows/ci.yml) runs scripts/generate.sh --check, which regenerates into a temp dir and fails the build if src/ has drifted from the proto contract — so a stale checkout can never be released. Once this commit lands on main, the tag-release automation publishes it like any other change.

Publishing to Packagist

The repository is already Packagist-ready; the prerequisites that live here are:

• a valid composer.json (composer validate --strict passes in CI),
• an OSI LICENSE,
• PSR-4 autoloading with the generated code committed under src/,
• SemVer git tags as the version source,
• tag-release.yml to cut those tags automatically once CI is green.

Packagist refreshes itself from its own GitHub webhook on every tag push, so — unlike the original design — nothing in this repo calls the Packagist API. There is no release.yml and no PACKAGIST_* secret.

One-time setup:

1. Push this folder to its own GitHub repo: https://github.com/CS-Nyx2/protobuf-php.
2. On packagist.org, Submit that repository URL.
3. Enable the GitHub service hook (Packagist shows the exact steps) so each tag push auto-updates the package. This webhook is the only link to Packagist — the tag-release workflow just pushes the tag and the hook does the rest.
4. Add the SUBMODULE_TOKEN secret (below).

Required CI secret

The protobuf submodule lives in the private CS-Nyx2/protobuf repo, so the workflows can't fetch it with the default GITHUB_TOKEN. Add one repository secret (Settings → Secrets and variables → Actions):

tag-release.yml needs no secret — it tags with the built-in GITHUB_TOKEN (permissions: contents: write) and never touches the submodule. (If CS-Nyx2/protobuf is later made public, drop SUBMODULE_TOKEN and the token: lines, though sync-protobuf.yml still needs write to push.)

Cutting a release manually

You rarely need to — a release tag is pushed automatically whenever CI passes on main with PHP/composer changes. Reach for a manual tag only to bump the minor or major version (the automation always patch-bumps the highest existing tag):

git tag v1.0.0
git push origin v1.0.0     # Packagist's GitHub hook picks it up

The next automated release then continues patch-bumping from v1.0.0. Packagist exposes the tag for composer require within moments of the push.

Note: the package is published as coolstudio/nyx-protobuf (Packagist vendor coolstudio) by CoolStudio (https://cool.studio) under an MIT license. The GitHub URLs above still point at the CS-Nyx2 org that hosts the repos.