Phalcon IDE Stubs

To enable autocompletion for the Phalcon Framework in your modern IDE, install the stubs as a development dependency using Composer.

composer require --dev phalcon/ide-stubs

Alternatively, you can install the stubs manually:

1. Clone the Phalcon IDE Stubs repository to a common location on your machine.
2. Configure your IDE to include this repository in its include path for autocompletion.

Stubs are automatically generated from the cphalcon project using Zephir stubs. If you find an error in the stubs, do not submit a PR to this repository. Instead:

1. Locate the error within the Phalcon Zephir code.
2. Submit a pull request with the fix to the phalcon/cphalcon repository.

In the Phalcon ADR (Application Design Pattern) implementation, the Phalcon\ADR\Payload\Status class distinguishes between two types of unsuccessful outcomes. Understanding this distinction is critical for proper error handling and domain logic flow:

• ERROR: Indicates that an exception was raised while the domain layer was executing. By convention, this status is paired with Payload::withException().
• FAILURE: Indicates that the domain layer ran to completion successfully but declined the request (e.g., a business rule was not satisfied). No exception was raised in this case.

Using FAILURE instead of ERROR allows you to represent expected business logic rejections without the overhead or flow-interruption of an exception.

Dispatching is the process of taking command-line arguments and extracting the module name, task name, action name, and optional parameters. The Phalcon\Cli\Dispatcher then instantiates the corresponding task and calls the specified action on it.

When an action method is called, any CLI options collected by the dispatcher are appended to the positional parameters. This means a task action receives options as trailing arguments after its declared positional parameters.

use Phalcon\Di\Di;
use Phalcon\Cli\Dispatcher;

$di = new Di();

$dispatcher = new Dispatcher();

$dispatcher->setDi($di);

$dispatcher->setTaskName("posts");
$dispatcher->setActionName("index");
$dispatcher->setParams([]);

$handle = $dispatcher->dispatch();

In Phalcon CLI routing, Phalcon\Cli\Router always constructs and returns the concrete Phalcon\Cli\Router\Route class. Because there is no injection point for externally built routes, RouteInterface serves primarily as a marker interface for type hinting in your application code rather than a contract you implement yourself.

Note that the fluent route API (such as beforeMatch(), getBeforeMatch(), convert(), and getConverters()) is available on the concrete Route class, not on this interface.

The Phalcon\Di\FactoryDefault\Cli class is a specialized variant of the standard Phalcon\Di. It is designed specifically for CLI (Command Line Interface) applications.

When instantiated, it automatically registers all framework services required for a CLI environment, such as Phalcon\Cli\Dispatcher and Phalcon\Cli\Router, saving the developer from registering each service individually.

use Phalcon\Di\FactoryDefault\Cli;

$di = new Cli();
// The DI container is now pre-populated with services suitable for CLI usage.

The Phalcon\ADR\Payload\Payload class is an immutable data structure produced by the domain layer in an ADR (Action-Domain-Responder) implementation. Because it is immutable, any method prefixed with with* (e.g., withResult(), withStatus()) will return a new instance of the payload, leaving the original object unchanged.

Use the provided static factory methods to quickly create payloads with predefined statuses, such as success(), error(), or notFound().

use Phalcon\ADR\Payload\Payload;

// Create a success payload with a result
$payload = Payload::success($someResult);

// Create a new instance with additional messages (immutability)
$payloadWithMessages = $payload->withMessages(['Operation completed successfully']);

// Access data
$status = $payloadWithMessages->getStatus();
$result = $payloadWithMessages->getResult();

To implement a command-line task (such as migrations, cronjobs, or unit tests), you must extend the Phalcon\Cli\Task class.

Tasks are composed of 'action' methods. By convention, these methods are named with an Action suffix (e.g., mainAction, findAction).

When an action is executed, it receives routed parameters as positional arguments. Any CLI options collected by the dispatcher are appended as trailing arguments. To capture these options, declare optional trailing parameters in your method signature.

class HelloTask extends \Phalcon\Cli\Task
{
    // This action will be executed by default
    public function mainAction()
    {
        // Task logic here
    }

    public function findAction()
    {
        // Specific action logic here
    }
}