Switch your stack between PHP and .NET without rewriting your app.

What stays the same when you switch

Eight surfaces are byte-compatible across the two runtimes. Verified against production deployments — the feedback files in the repo (SHAPE-FEEDBACK.md, TOCSBE-FEEDBACK.md) document each item with commit SHAs.

Migration in four steps

A straightforward deployment exercise — no data migration, no code rewrite.

1. Install the new runtime Stand up the .NET (or PHP) build alongside your existing one. Same machine works; separate hosts work; Docker container works. The two don't need to know about each other.
2. Point at the same config and database Pass the same config/shape.json path. Use the same DSN, JWT secret, OIDC config. Both runtimes are read-only on those inputs.
3. Diff the surfaces curl -s OLD/api.php?manifest | jq -S versus the new runtime's. Same for ?openapi and a sample ?op=query. Should be byte-equivalent except for the runtime-identity field. Frontend smoke-test passes unchanged.
4. Switch traffic Flip the DNS record, the load balancer pool, or the reverse-proxy upstream directive. Reverse to roll back. The two runtimes can also coexist in production behind a weighted split for staged rollout.

The same JSON config, two runtimes

Below: identical config/shape.json consumed by the PHP entry point and the .NET entry point. The application layer is this small.

<?php
require __DIR__ . '/../vendor/autoload.php';

Shape\ShapeApp::run(__DIR__ . '/..');
// Discovers config/database.php (or config/shape.json),
// merges env.local.php, dispatches to ShapeRouter::run.

using Shape;

await ShapeApp.Run("config/shape.json", args);
// Reads the same JSON config (masks, access, DSN, OIDC),
// overlays DB_DSN / JWT_SECRET / CLOUD_SQL_INSTANCE env vars,
// dispatches to MapShape on a Kestrel host.

Both runtimes read the same config/shape.json shape. Masks support two authoring styles in the same block — an external sqlFile reference for queries you want under version control as standalone .sql assets, and inline sql with typed params for short queries you want to read alongside the config:

{
    "db":     { "dsn": "pgsql:host=...;dbname=...", "user": "...", "pass": "..." },
    "access": { "admin": ["customers", "invoices", "products"] },
    "auth": {
        "driver": "jwt",
        "oidc": {
            "preset":       "entra",
            "tenant_id":    "...",
            "audience":     "api://my-app",
            "role_mapping": { "Backend.Admin": "admin" }
        }
    },
    "masks": {
        "reports.topCustomers": {
            "sqlFile":     "queries/top-customers.sql",
            "roles":       ["admin"],
            "description": "Top 20 customers by revenue."
        },

        "orders.recentByRegion": {
            "sql": "SELECT id, customer_id, total, created_at FROM orders WHERE region = :region AND created_at >= :since ORDER BY created_at DESC LIMIT 50",
            "params": {
                "region": { "type": "string", "required": true },
                "since":  { "type": "string", "required": true }
            },
            "roles":       ["admin", "manager"],
            "description": "Last 50 orders for a region since a given date."
        }
    }
}

Both styles share the same :param placeholder syntax, the same role-gating, the same description-into-manifest passthrough, and the same OData query options at call time (?$top, ?$skip, ?$orderby). Pick whichever style fits the SQL — short hand-written queries inline, long reporting queries in their own file under queries/*.sql.

FAQ