Composer repositories: today and tomorrow

Every Flyokai project currently lists ~25 inline git@github.fly:flyokai/* repositories in the project's composer.json. Each new framework module means another entry in every consumer. This document records why we do that today, the pain it causes, and the recommended migration path.

Today: inline repositories block

"repositories": [
    { "name": "flyokai-flyokai",        "type": "git", "url": "git@github.fly:flyokai/flyokai.git" },
    { "name": "flyokai-application",    "type": "git", "url": "git@github.fly:flyokai/application.git" },
    { "name": "flyokai-amphp-injector", "type": "git", "url": "git@github.fly:flyokai/amphp-injector.git" },
    …  // ~25 entries
]

Why it works today

• No infrastructure to stand up.
• Every package is exactly one git URL away.
• Easy to add ad-hoc forks for testing.

Why it doesn't scale

• Every new framework module requires a coordinated edit across every consumer's composer.json.
• Two editions (webapi, data-service) plus any number of downstream projects → N copies of essentially the same list.
• Subtle drift: an entry forgotten in one edition leads to "package not found" errors only when that edition is created.
• 35+ repos slows down composer update because Composer probes every URL on resolution.

Recommended: a private Composer repository (Satis)

Replace the inline list with a single Composer repository pointing at a Satis (or Packeton) instance that aggregates every git@github.fly:flyokai/* repo.

"repositories": [
    { "type": "composer", "url": "https://packages.flyokai.internal" }
]

Migration plan

1. Stand up Satis at packages.flyokai.internal (or wherever it fits in your infrastructure).

composer create-project composer/satis ~/satis dev-main

1. Configure ~/satis/satis.json to mirror every git@github.fly:flyokai/* repo:

{
    "name": "flyokai/private-packages",
    "homepage": "https://packages.flyokai.internal",
    "repositories": [
        { "type": "git", "url": "git@github.fly:flyokai/flyokai.git" },
        { "type": "git", "url": "git@github.fly:flyokai/application.git" },
        ... // every flyokai/* repo
    ],
    "require-all": true,
    "archive": {
        "directory": "dist",
        "format": "tar"
    }
}

1. Build the index on every push (CI hook, cron, or webhook):

php ~/satis/bin/satis build ~/satis/satis.json /var/www/satis-output/

1. Deploy /var/www/satis-output/ behind nginx/Apache + TLS (it's static HTML/JSON).

2. Update every project's composer.json to drop the inline repositories block in favour of one entry pointing at Satis:

"repositories": [
    { "type": "composer", "url": "https://packages.flyokai.internal" }
]

1. Drop legacy entries gradually if you must — mixed inline + composer-repository works fine while you migrate.

What this gets you

• One source of truth for the package list.
• Adding a new framework module → one edit in satis.json instead of N.
• Faster composer update: Composer only probes Satis once.
• Optional dist tarballs (faster CI installs than git clones).
• Free per-package metadata page (e.g. https://packages.flyokai.internal/p/flyokai/application.json).

Caveats

• Authentication: SSH keys still need to be present where Satis runs. Anyone consuming the Satis URL also needs HTTP-level auth or VPN access if the index is private.
• Index freshness: the Satis build is a batch job. If you push to a flyokai/* repo and immediately run composer update, the Satis index won't see the new commit until the next build.
• Branch-resolution constraints (dev-dev) work the same way they do today — Satis just exposes them.

When to defer

If only one or two editions exist and the framework is fairly stable, keeping the inline repositories block is fine. Migrate when you find yourself editing 4+ composer.json files for one new module — that's when the cost flips.