feat(console): render Cycle schema to PHP file (+roles filter, overwrite)

[petrdobr]

• New option to write Cycle ORM schema to a PHP file for cycle:render
• Filter by roles to limit the exported subset
• Overwrite flag to safely replace existing file

What was changed

• Extended the existing cycle:render console command:
  • -o, --output=/path/to/schema.php — writes rendered schema to a file (supported only for format=php).
  • --overwrite — allows replacing an existing output file.
  • -r, --role=<role> [--role=<role> ...] — filters the rendered schema by roles; accepts multiple flags and comma-separated values (e.g. --role=auth,rbac --role=default).
• STDOUT behavior for all formats is preserved. If --output is not provided, output goes to STDOUT as before.
• For non-php formats with --output, the command fails with an explicit error.
• Safe write: content is written to a temporary file in the target directory and then atomically moved to the destination; parent directories are created as needed.

Examples

# to stdout (unchanged)
php app.php cycle:render php

# to file
php app.php cycle:render php --output=var/schema.php

# filter by roles (comma-separated, or multiple --role flags)
php app.php cycle:render php --output=var/schema.auth.php --role=auth,rbac
php app.php cycle:render php --output=var/schema.default.php --role=default --overwrite

Edge cases & messages

• Unknown roles are reported as a warning and ignored.
• If the role filter yields no entries:
  • with --output → prints “Nothing to write.” and exits successfully;
  • without --output → prints an empty line to STDOUT.
• If the destination file already exists without --overwrite, the command fails with an explicit message.
• Directory creation and file write failures are reported with descriptive errors.

Why?

• A deterministic PHP artifact of the schema is useful for audits, code reviews, caching in CI and reproducible builds.
• Role-based filtering keeps artifacts minimal and context-specific (e.g., exporting only auth-related roles).
• Preserving STDOUT behavior keeps the command backward compatible, while --output enables file-based workflows.

Checklist

• Closes Add console command for Schema rendering into PHP file #29
• Tested
  • Tested manually
  • Unit tests added

Documentation

New options:

• -o, --output=PATH — write rendered schema to a PHP file (supported only when format=php).
• --overwrite — allow replacing an existing output file.
• -r, --role=ROLE — filter exported schema by roles (for any format).
  Accepts multiple flags and comma-separated values inside a flag (e.g. --role=auth,rbac --role=default).
  Role matching is case-insensitive; unknown roles are ignored with a warning.

Behavior & edge cases:

• Without --output the command writes to STDOUT (unchanged behavior).
• If --output is used with a non-php format → the command fails with an explicit error.
• If filtering results in an empty schema:
  • with --output → prints “Nothing to write.” and exits successfully;
  • without --output → prints an empty line to STDOUT.
• Safe write: schema is written to a temp file in the target dir and then atomically moved; parent dirs are created if missing.

Examples

# stdout (unchanged)
php app.php cycle:render php

# write to file
php app.php cycle:render php --output=var/schema.php

# filter by roles (comma-separated or multiple flags)
php app.php cycle:render php --output=var/schema.auth.php --role=auth,rbac
php app.php cycle:render php --output=var/schema.default.php --role=default --overwrite

[roxblnfk]

And eah, please don't overwrite reviewed commits via force pushe

[petrdobr]

And eah, please don't overwrite reviewed commits via force pushe

Understood, sorry for rewriting them earlier and thanks for the advice :)

[roxblnfk]

Good feature, thanks