Getting Started

This guide gets you from install to a runnable Phalcon Kit application. If your main goal is a REST API, read this first and then continue with the Build Your First REST Resource.

By the end, you will have:

• dependencies installed against the current package requirements;
• environment-backed application configuration;
• working HTTP, CLI, and WebSocket entrypoints;
• a local HTTP process you can inspect with curl;
• the next commands for migrations, scaffolding, and tests.

Verify the platform before creating the project:

php --version
php -r 'echo phpversion("phalcon") ?: "phalcon not loaded", PHP_EOL;'
composer --version

1. Create Or Install

For a new application, start from the phalcon-kit/app skeleton:

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

For an existing Phalcon application:

composer require phalcon-kit/core

Use phalcon-kit/core for new projects. The old zemit-cms/core package name exists only for historical projects and pinned legacy installs.

2. Configure The Environment

Create or update .env:

APP_NAME="My API"

DATABASE_HOST=127.0.0.1
DATABASE_DBNAME=my_api
DATABASE_USERNAME=my_api
DATABASE_PASSWORD=secret

The app config reads environment values and registers modules, providers, aliases, permissions, and integrations. Keep secrets in .env; keep structure in app/Config.

3. Check The Project Shape

A normal app has a small bootstrap and clear ownership boundaries:

app/
  Bootstrap.php
  Config/
  Models/
  Modules/Api/
resources/
  migrations/
public/
  index.php
loader.php
index.php
cli
websocket

Point the web server at public/, not the project root.

4. Run Locally

For a quick local test:

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

In another terminal, inspect the response:

curl --include http://127.0.0.1:8000/

A configured application response—or even an application-owned 404—proves the request reached bootstrap and dispatch. A PHP source download, web-server 404, or connection refusal means the request did not reach the application.

For production-like development, use PHP-FPM behind Nginx, Apache, Caddy, or a container proxy. See Web Server And WebSocket.

5. Verify Tooling

After installing dependencies:

composer validate --strict --no-check-publish
composer phpunit

If the application uses the database:

./bin/migration-list.sh
./bin/migration-run.sh

6. Build The First API Resource

The fastest path is:

1. Create the table.
2. Run migrations.
3. Run the scaffolder.
4. Add a model-backed API controller.
5. Configure permissions.

The full example is in Build Your First REST Resource.

Useful Entrypoints

Web entrypoint:

<?php

use App\Bootstrap;

require 'loader.php';

echo (new Bootstrap())->run();

CLI entrypoint:

#!/usr/bin/env php
<?php

use App\Bootstrap;

require 'loader.php';

echo (new Bootstrap('cli'))->run();

WebSocket entrypoint:

#!/usr/bin/env php
<?php

use App\Bootstrap;

require 'loader.php';

echo (new Bootstrap('ws'))->run();

Next Steps

• Build Your First REST Resource: build a complete resource.
• Configuration: configure modules, providers, aliases, and permissions.
• Database And Scaffolding: generate model layers.
• REST APIs: configure resource controllers.
• Developer Cookbook: copy focused application recipes.
• Troubleshooting: diagnose boot, DI, routing, database, and runtime problems.

Common Setup Problems

For a systematic diagnostic flow, use Troubleshooting.