Phalcon Kit Core

Build Phalcon applications faster, especially REST APIs backed by a real database schema.

Phalcon Kit Core sits on top of the Phalcon PHP Framework and gives you the application plumbing most teams write again and again: bootstrap, config, providers, REST controllers, model scaffolding, eager loading, identity, permissions, CLI tasks, WebSocket workers, logging, helpers, and quality tooling.

You still write normal Phalcon/PHP. Phalcon Kit handles the repetitive structure so you can spend more time on the resource rules, business logic, and product behavior.

Quick Start

Start a new application from the phalcon-kit/app skeleton:

composer create-project phalcon-kit/app my-api

Add the core package to an existing Phalcon application:

composer require phalcon-kit/core

New projects should use phalcon-kit/core. Older projects may still reference zemit-cms/core, the previous package name. Keep old projects pinned until you are ready to test the package name migration.

Why Use It

Use Phalcon Kit when you want Phalcon's speed and low-level control, but you do not want every project to re-invent the same API and model infrastructure.

It is useful when you need to:

• turn database tables into typed Phalcon models;
• expose model-backed REST resources quickly;
• save nested one-to-many or many-to-many payloads;
• filter, search, sort, paginate, and eager-load relations consistently;
• restrict rows by user, role, project, workspace, tenant, or ownership rules;
• use JWT/session identity, impersonation, and role-based access control;
• keep CLI, WebSocket, API, and web modules on the same bootstrap/config;
• let generated model code track the database while concrete models stay clean.

From Database To API

The usual workflow is:

1. Create or update the database schema.
2. Run migrations.
3. Run the scaffolder.
4. Add business logic to concrete models.
5. Add a small REST controller that declares save/filter/search/eager-load policy.

Example resource controller:

<?php

namespace App\Modules\Api\Controllers;

use Phalcon\Support\Collection;

final class FooBarController extends AbstractController
{
    public function initializeSaveFields(): void
    {
        $this->setSaveFields(new Collection([
            'label',
            'status',
            'usernode' => [
                'userId',
                'type',
                'deleted',
            ],
        ]));
    }

    public function initializeFilterFields(): void
    {
        $this->setFilterFields(new Collection([
            'id',
            'label',
            'status',
            'UserNode.userId',
            'UserNode.type',
            'deleted',
        ]));
    }

    public function initializeWith(): void
    {
        $this->setWith(new Collection([
            'UserNode.UserEntity',
        ]));
    }
}

That controller participates in the standard REST flow: list/detail lookup, save/create/update, delete/restore, filter/search/order/limit handling, relation assignment, exposers or transformers, eager loading, and permission conditions.

See Build Your First REST Resource for the complete schema-to-controller example with request and response payloads.

What You Write

You write	Phalcon Kit handles
Database schema and migrations	Generated model abstracts, accessors, column maps, validations, relationships
Concrete model behavior	Shared model base, behaviors, soft delete, UUIDs, slug, blameable fields
REST resource policy	Request parsing, filtering, searching, saving, exposing, eager loading
Permission config and row rules	ACL expansion, role inheritance, controller/model/task checks
Transformers for complex output	Fractal manager helpers and relation-loaded includes
CLI/WebSocket task logic	Shared bootstrap, DI services, config, identity context

Application Shape

Most applications using this package follow this shape:

app/
  Config/             app config, providers, permissions
  Models/             concrete business logic
  Models/Abstracts/   generated schema layer
  Modules/Api/        REST controllers
  Modules/Cli/        CLI tasks
  Modules/Ws/         WebSocket tasks
resources/
  migrations/         database migrations
public/
  index.php           web front controller

Generated files mirror the database. Your concrete models, controllers, config, services, transformers, and tasks remain application-owned.

Requirements

• PHP >= 8.5
• Phalcon ^5.13
• Composer
• A PDO-compatible database supported by Phalcon
• MySQL 8+ for the core test/scaffold baseline

Recommended extensions for common applications: APCu, Redis, Swoole, Opcache, IMAP, sockets, SimpleXML, and GD.

Learn By Task

• Build your first resource: Build Your First REST Resource
• Start a project: Getting Started
• Configure modules and providers: Configuration
• Generate models from a database: Database And Scaffolding
• Avoid N+1 queries: Models And Eager Loading
• Build model-backed APIs: REST APIs
• Add roles and row-level access: Identity And Permissions
• Deploy behind PHP-FPM or WebSocket proxying: Web Server And WebSocket
• Run checks before release: Quality And Maintenance
• Use the bundled AI skills: AI-Assisted Development
• Migrate from the old package name: Migration From zemit-cms/core
• Migrate old RESTful resources: Migrate RESTful 0.x Resources To 1.x

The full guide index is in guides/README.md.

FAQ

Is Phalcon Kit a replacement for Phalcon?

No. Phalcon Kit extends Phalcon. You still use Phalcon models, controllers, services, DI, routing, validation, and events. Phalcon Kit adds application structure, scaffolding, REST conventions, identity, permissions, and reusable helpers around them.

Do I need to know Phalcon?

Yes, at least the basics. Phalcon Kit is most useful when you want to build with Phalcon but avoid repeatedly writing the same model/API/permission plumbing.

Does it generate controllers?

The main supported scaffolding path is model generation from the database: abstracts, interfaces, relationships, validations, enum classes, and tests. REST controllers are usually small app-owned classes because save/filter/expose policy is business-specific.

Should I use exposers or transformers?

Use exposers for simple CRUD output. Use transformers when public clients need a stable response shape, conditional includes, renamed fields, or better control over nested resources.

Can I use Nginx instead of Apache?

Yes. Phalcon Kit needs a web server or proxy that serves public/ and forwards PHP requests to PHP-FPM. Nginx, Apache, Caddy, containers, and platform proxies are all valid.

What happened to zemit-cms/core?

zemit-cms/core is the historical package name. New projects should install phalcon-kit/core. Existing projects can stay pinned until they are ready to test the package-name migration.

For Contributors

composer qa
composer qa:static
composer qa:security
composer qa:test
composer qa:style

See CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md before opening a pull request.

AI-Assisted Development

Phalcon Kit includes optional agent instructions under resources/skills/. They help AI coding agents follow the same PhalconKit conventions documented in the human-facing guides: database-first scaffolding, REST resources, eager loading, transformers, identity, permissions, CLI tasks, WebSocket workers, and provider/config patterns. They do not add runtime AI behavior or change PHP APIs.

See AI-Assisted Development for the bundled skills, example prompts, safety defaults, and maintainer rules for keeping human docs and agent references synchronized.

Package History

Phalcon Kit Core continues the package formerly known as zemit-cms/core. Existing projects can stay on pinned legacy constraints until migration is planned. New installations should use phalcon-kit/core.

License

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

(c) 2017-present, Phalcon Kit Team. All rights reserved.