README

Start a modern Phalcon application with Phalcon Kit's HTTP, CLI, and optional WebSocket runtimes, permissions, database scaffolding, and production-oriented project layout already connected.

The reference skeleton keeps each module thin. Application code belongs to your project; the reusable framework behavior stays in phalcon-kit/core.

Requirements

PHP 8.5 or newer
Phalcon 5.20.3 or newer on the 5.x release line
Composer 2
A PDO-compatible database for model-backed features
Optional: Swoole 6.2 for the WebSocket server

MySQL 8 is the primary migration and scaffolding baseline, but PhalconKit can use other PDO adapters supported by Phalcon.

See the official Phalcon installation guide for extension installation instructions.

Create A Project

composer create-project phalcon-kit/app:^2.0 my-app
cd my-app
cp .env.example .env
composer qa

Update .env for the application and database before enabling model-backed services. Do not commit .env or production credentials.

For local development with PHP's built-in server:

php -S 127.0.0.1:8080 -t public public/index.php

For Apache, Nginx, Caddy, containers, or a platform proxy, configure public/ as the document root. Never expose the repository root as the web root.

Project Layout

src/
  Bootstrap.php         Application bootstrap
  Config.php            Modules, providers, aliases, and permissions
  Models/               Application and generated models
  Modules/
    Admin/               Admin controllers
    Api/                 REST API controllers
    Cli/                 CLI tasks
    Frontend/            Browser-facing controllers
    Ws/                  Optional WebSocket tasks
bin/                    CLI and WebSocket runtime entrypoints
public/                 Web document root
resources/migrations/  Database migrations
scripts/                Migration, scaffolding, and maintainer helpers
storage/                Cache, logs, files, backups, and runtime data
tests/Unit/             Application tests
bootstrap.php           Paths and Composer autoloading

App\ is PSR-4 autoloaded from src/. Environment-specific values belong in .env; structural application policy belongs in src/Config.php.

Frontend and API index actions are public examples. The Admin module is registered as an extension point but has no anonymous permission by default; grant its controllers only to application roles that require them.

CLI

The project CLI loads App\Bootstrap, so project modules and tasks are available alongside the tasks supplied by Core:

./bin/phalcon-kit --help
./bin/phalcon-kit cli cron run

The launcher resolves the project root from its own path, so it can be invoked from any working directory. Windows users can run bin\phalcon-kit.bat.

WebSocket

The optional WebSocket example accepts only {"type":"ping"} and answers with {"type":"pong"}. It does not expose anonymous subscription or broadcast behavior.

Install Swoole in the PHP runtime that will own the long-running worker, then start it with:

./bin/websocket

The default listener is 127.0.0.1:8081. Override the commented SWOOLE_* values in .env when necessary. Keep loopback binding when Apache, Nginx, Caddy, or another trusted proxy terminates TLS; containers can bind to 0.0.0.0 on an isolated network.

The committed swoole/ide-helper package is development-only and does not install the extension. Production should run the worker under a supervisor and proxy a dedicated path such as /ws/ to it. See Web Server And WebSocket for proxy, container, systemd, and operational guidance.

Migrations And Models

The migration helpers use the maintained phalcon/migrations package:

./scripts/migration-list.sh
./scripts/migration-generate.sh
./scripts/migration-run.sh
./scripts/migration-rollback.sh --version=1.0.0

Generate missing model layers from the connected database:

./scripts/generate-models.sh

This command refuses --force, keeps concrete model business logic intact, and makes generated abstracts inherit from the application-owned App\Models\AbstractModel extension point.

Regenerate generated layers while preserving concrete application models:

./scripts/regenerate-models.sh

Both helpers deliberately skip controllers and generated tests; those remain application-owned code in this skeleton.

PowerShell equivalents are included for Windows.

Quality Checks

The lockfile is committed deliberately: every newly created application starts from the exact dependency graph validated by this repository.

composer qa       # Composer validation/audit, PHPCS, PHPStan, PHPUnit
composer phpcs    # PSR-12-based coding standards
composer phpstan  # Static analysis
composer phpunit  # Unit tests
composer phpcbf   # Apply safe coding-standard fixes

Run composer update intentionally and review both composer.json and composer.lock before committing dependency changes.

Documentation

Support And Security

Use the App issue tracker for skeleton, installation, entrypoint, or helper-script problems. Use the Core issue tracker for reusable framework behavior.

Please read SECURITY.md before reporting a vulnerability and CONTRIBUTING.md before proposing a change. Applications upgrading from the 1.x skeleton should also read UPGRADE.md.

Package History

Phalcon Kit App continues the application skeleton formerly published for Zemit CMS. New projects should use phalcon-kit/app and phalcon-kit/core.

License

Phalcon Kit App is released under the BSD 3-Clause License.

phalcon-kit / app

Package info

Security

Fund package maintenance!

Statistics