{"id":50926021,"url":"https://github.com/wnunezc/catalyst","last_synced_at":"2026-06-16T23:02:58.614Z","repository":{"id":362171857,"uuid":"1255775081","full_name":"wnunezc/catalyst","owner":"wnunezc","description":"Catalyst PHP Framework - lightweight MVC framework with distributable dual-space architecture","archived":false,"fork":false,"pushed_at":"2026-06-15T03:46:51.000Z","size":22534,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T05:16:20.643Z","etag":null,"topics":["calendar","catalyst","framework","modular-framework","mvc","php","php84","rbac","reporting","workflow"],"latest_commit_sha":null,"homepage":"https://catalyst.lh-2.net","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wnunezc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security-conventions.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-01T06:52:27.000Z","updated_at":"2026-06-15T03:40:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wnunezc/catalyst","commit_stats":null,"previous_names":["wnunezc/catalyst"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/wnunezc/catalyst","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wnunezc%2Fcatalyst","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wnunezc%2Fcatalyst/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wnunezc%2Fcatalyst/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wnunezc%2Fcatalyst/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wnunezc","download_url":"https://codeload.github.com/wnunezc/catalyst/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wnunezc%2Fcatalyst/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34426745,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar","catalyst","framework","modular-framework","mvc","php","php84","rbac","reporting","workflow"],"created_at":"2026-06-16T23:02:57.144Z","updated_at":"2026-06-16T23:02:58.604Z","avatar_url":"https://github.com/wnunezc.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Catalyst PHP Framework\n\nCatalyst is a PHP 8.4 MVC framework distributed as a project base, not as a\nComposer package. It is meant to be copied or cloned as the starting point for a\nweb application, then configured through local environment files and the setup\nwizard.\n\nCurrent distribution target: `0.2.0-rc.2`.\n\n## Runtime Model\n\n- Web entry point: `public/index.php`.\n- CLI entry point: `public/cli.php`.\n- Project root: the directory that contains `app/`, `boot-core/`, `public/`,\n  `Repository/`, `composer.json` and this README.\n- Effective web root: `public/`.\n\nThe physical folder name is not part of runtime path resolution. Catalyst\ncalculates its project directory from the relative structure of the entry points\nand bootstrap files, so it must not depend on a folder named `catalyst`.\n\n## Installation Contract\n\nInstall the contents of this project into the target site root. For a local\nXAMPP-style setup, this means `htdocs` can contain the Catalyst project files\ndirectly:\n\n```text\nhtdocs/\n├── app/\n├── boot-core/\n├── public/\n├── Repository/\n├── vendor/\n├── composer.json\n└── README.md\n```\n\nThe preferred Apache configuration is to point the VirtualHost `DocumentRoot` to\n`public/`:\n\n```apacheconf\nDocumentRoot \"C:/xampp/htdocs/public\"\n\u003cDirectory \"C:/xampp/htdocs/public\"\u003e\n    AllowOverride All\n    Require all granted\n\u003c/Directory\u003e\n```\n\nIf Apache is pointed at the project root instead, the root `.htaccess` forwards\nrequests internally to `public/` and blocks direct access to sensitive project\ndirectories. That fallback is for portability; production hosts should still use\n`public/` as the document root when possible.\n\nDo not publish or rely on a URL shape that exposes the project folder as a path\nsegment. If a developer chooses a subdirectory deployment anyway, it must be\ntreated as an environment-specific concern and not as the default Catalyst\ncontract.\n\n## Supported Local Stacks\n\nCatalyst requires PHP 8.4, Composer and MySQL/MariaDB. The local stack can be\nXAMPP, WSDD/Docker, Laragon, MAMP or another equivalent PHP/Apache setup.\n\n`https://catalyst.dock/` is only the maintainer's WSDD local URL. A clean local\ninstall should normally start from `http://localhost/`, a local VirtualHost, or\nwhatever URL the developer configures in the setup wizard.\n\n## First Run\n\nInstall dependencies:\n\n```powershell\ncomposer install\ncomposer dump-autoload\n```\n\nCreate local environment files:\n\n- copy `boot-core/config/env/.env.example` to `boot-core/config/env/.env`;\n- generate and set `APP_KEY`;\n- set only the local secrets needed for first boot;\n- do not commit `.env`, DKIM keys, `secrets.json`, uploads, logs or runtime\n  storage.\n\nConfirm the CLI is available:\n\n```powershell\nphp public/cli.php help\nphp public/cli.php status\n```\n\nOpen the setup wizard at the configured local URL:\n\n```text\nhttp://localhost/configuration/environment-setup\n```\n\nUse the wizard to configure app URL, database, mail, session, cache, logging,\nsecurity, WebSocket and DKIM values as needed. Database credentials, mail\ncredentials, OAuth secrets, FTP credentials and DKIM keys belong to the\ndeveloper's environment, not to the distributed base.\n\n## Project Repositories And Updates\n\nA derived application should keep the full Catalyst project in its own Git\nrepository. For example, an ERP project can use `origin` for the application\nrepository and keep Catalyst as `upstream`:\n\n```powershell\ngit remote add upstream https://github.com/wnunezc/catalyst.git\ngit fetch upstream --tags\n```\n\nApplication work should live primarily under:\n\n```text\nRepository/App/\n```\n\nThe framework/application boundary is documented in `docs/app-boundary.md`.\nRun `php public/cli.php inspect:lint` to detect common boundary violations such\nas application modules under `app/`, unsupported `Repository/*` roots or source\nassets placed directly under `public/assets/app`.\n\nFramework-owned updates normally come from:\n\n```text\napp/\nRepository/Framework/\nboot-core/\npublic/assets/js/catalyst/\npublic/assets/css/catalyst/\ndocs/\n```\n\n`v0.2.0-rc.1` is a structural upgrade from `v0.1.0-rc.8`. Review\n`docs/workflow/release-v0.2.0-rc.1.md` before merging it into a derived\napplication. The release consolidates module ownership, the canonical document\nand shell, frontend runtime, internal transports, UI composition and testing\nownership.\n\n`v0.2.0-rc.2` is the corrective and security-hardening follow-up. Review\n`docs/workflow/release-v0.2.0-rc.2.md` before updating from RC1, especially\nwhen the RC1 feature-flag migration journal contains persisted rows.\n\nTo check the installed Catalyst version:\n\n```powershell\nphp public/cli.php version\nphp public/cli.php update:check\n```\n\n`update:check` is informational. It does not merge code or modify the working\ntree. When a newer release is available, review release notes and update through\nGit:\n\n```powershell\ngit fetch upstream --tags\ngit merge v0.1.1\nphp public/cli.php quality:check\n```\n\nResolve conflicts carefully. In a healthy derived project, most application\nconflicts should stay inside `Repository/App/`; framework updates should avoid\noverwriting application-specific code.\n\n## Configuration Baseline\n\nPortable starter configuration lives in:\n\n```text\nboot-core/config/templates/\n```\n\nThese templates intentionally avoid maintainer-specific URLs, database hosts,\nmail accounts and secrets. Runtime configuration is loaded from:\n\n```text\nboot-core/config/{environment}/*.json\nboot-core/config/env/.env\n```\n\nEnvironment directories such as `boot-core/config/development/` are local-only\nruntime state and are ignored by Git. Catalyst tracks neutral templates in\n`boot-core/config/templates/`, then creates or syncs the active environment\nfiles without overwriting local values:\n\n```powershell\nphp public/cli.php config:sync\nphp public/cli.php config:contract-smoke --json\nphp public/cli.php config:e2e-readiness --json\n```\n\nThe setup wizard materializes project-specific configuration. Release exports\nmust exclude runtime secrets, active local config, private artifacts and storage.\n\n## Platform Capabilities\n\n- Route registration, route linting and route cache tooling.\n- HTTP middleware, sessions, CSRF, CSP nonce support and trusted rendering\n  boundaries.\n- Auth with password reset, remember-me invalidation, MFA/TOTP, email\n  verification, configurable public registration, throttling, RBAC and resource\n  policies with ownership, visibility and context constraints.\n- ORM, QueryBuilder, migrations and database tooling.\n- Framework modules for API Platform, Audit, Auth, Automation, Catalogs,\n  DevTools, Documents, Media, Notification, Operations, Roles and Settings.\n- Global building blocks: CRUD scaffolding, `FormBuilder`, `DataGrid`, resource\n  abilities, audit log, metadata, media library, document templates, workflows,\n  automations and API tokens.\n- Reusable framework contracts for app boundary linting, update safety, safe\n  reverse cascade deletes, generic entity references, transactional sequences,\n  attachment policy and QR verification tokens, dynamic workflow approvals,\n  calendar providers, report providers and complex app scaffolding.\n- Guidance for adapting large product specs into Catalyst apps without creating\n  app-owned routers, kernels or framework forks.\n- CLI quality gates, inspectors, module catalog generation and runtime\n  inventory generation.\n- Separate framework-owned and app-owned test boundaries with external local\n  Playwright runtime, secrets and results.\n\n## Approved Composer Dependencies\n\nRuntime dependencies are limited to:\n\n- `phpmailer/phpmailer`\n- `league/oauth2-client`\n- `cboden/ratchet`\n- `react/http`\n\nDo not add Composer dependencies without an explicit project decision.\n\n## Quality Gate\n\nRun before committing framework, routing, security, config or asset changes:\n\n```powershell\ncomposer validate --strict\ncomposer audit\nphp public/cli.php route:lint\nphp public/cli.php inspect:lint\nphp public/cli.php security:check\nphp public/cli.php quality:check\nphp public/cli.php route:list --json\ngit diff --check\n```\n\nFor documentation/runtime reconciliation also run:\n\n```powershell\nphp public/cli.php docs:inventory --json\nphp public/cli.php docs:sync-runtime --stdout\n```\n\nEnvironment-specific warnings are acceptable only when blocker checks pass and\n`quality:check` reports the runtime as ready.\n\n## Repository Layout\n\n```text\napp/                      Core runtime: Kernel, HTTP, routing, middleware, ORM, CLI\nRepository/Framework/     Framework-owned modules\nRepository/App/           Application-owned surfaces and project code\nboot-core/bin/            Bootstrap-owned scripts and support entry helpers\nboot-core/cache/          Bootstrap/runtime cache artifacts\nboot-core/config/         JSON/env configuration and local runtime files\nboot-core/database/       Migrations and SQL artifacts\nboot-core/routes/         Global route files\nboot-core/storage/        Logs, throttle state and runtime artifacts\nboot-core/template/       Shared layouts, components, debug and error templates\npublic/                   Web entry point, CLI entry point and public assets\ndocs/                     Current technical documentation\nSTRUCTURE.md              Technical inventory and quick component map\nTERMINAL.md               CLI command reference\nAPI.md                    Subsystem index\n```\n\n## Documentation Map\n\n- [docs/workflow/first-run.md](docs/workflow/first-run.md) - fresh install workflow\n- [docs/workflow/reusable-base-install.md](docs/workflow/reusable-base-install.md) - reusable project base workflow\n- [docs/deployment.md](docs/deployment.md) - deployment and packaging boundaries\n- [docs/architecture.md](docs/architecture.md) - architecture and documentation index\n- [docs/ui/surface-architecture.md](docs/ui/surface-architecture.md) - document, shell, frontend runtime and surface ownership\n- [docs/runtime-module-catalog.md](docs/runtime-module-catalog.md) - live module and route catalog\n- [docs/runtime-inventory.md](docs/runtime-inventory.md) - generated class/template/script inventory\n- [docs/security-conventions.md](docs/security-conventions.md) - CSP, nonce and trusted HTML rules\n- [docs/quality-gate.md](docs/quality-gate.md) - local quality gate contract\n- [TERMINAL.md](TERMINAL.md) - CLI command reference\n\n## Distribution Status\n\n`0.2.0-rc.2` supersedes `v0.2.0-rc.1` with corrective migration ownership,\nportable framework tests and security hardening. The `0.2.0` line is intended\nfor developers who use Catalyst as a project base. It is not a public Composer\npackage and is not intended to be installed into another project's `vendor/`\ndirectory.\n\nBefore a release artifact is published, generate it from a clean checkout and\nexclude local secrets, DKIM keys, runtime storage, uploads, logs, ad-hoc zips and\nIDE files.\n\n## Notes\n\n- Runtime truth is the code first, then the living docs reconciled to runtime.\n- If a document contradicts runtime behavior, fix the document rather than\n  assuming the text is correct.\n- Historical process traceability belongs outside the framework hot path.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwnunezc%2Fcatalyst","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwnunezc%2Fcatalyst","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwnunezc%2Fcatalyst/lists"}