Overview

Phalcon, historically characterized by a modest development community and limited pull requests, faced challenges due to developers’ unfamiliarity with C, the language in which the framework was originally written. To encourage contributions, we introduced Zephir, a language closely resembling PHP and Javascript syntax. In 2003, we unveiled this initiative, subsequently releasing the language and transitioning all Phalcon code to Zephir. Since then, Zephir has been integral to Phalcon’s development.

The Challenge

Building a feature-rich framework necessitates a comprehensive development environment supporting various features and associated services. For example, validating ORM functionality across different database adapters (e.g., MySQL, Postgresql, Sqlite) requires the installation of relevant PHP extensions and databases. Similarly, to execute the testing suite for Phalcon’s extensive functionality, developers must install numerous extensions and services such as Redis and Memcached.

Considering the diverse PHP versions (e.g., PHP 8.1, 8.2), Phalcon’s development becomes intricate due to these prerequisites.

Solution

Formerly relying on `nanobox,“ a solution now discontinued, we intensified our efforts, adopting Docker to streamline development requirements. With just a few commands, developers can seamlessly contribute to Phalcon and execute tests promptly.

This Docker-based approach simplifies the setup, ensuring a more accessible and efficient development process for Phalcon.

Installation

Before you begin, ensure that docker is installed on your machine. If you haven’t installed it yet, follow the instructions here. Additionally, you’ll need docker compose - installation details can be found here.

Running the Development Environment

1. Fork the Repository Start by forking the cphalcon repository to your GitHub account. If you haven’t done this already, navigate to the cphalcon page in your browser and click the Fork button located at the top right of the screen.

2. Clone the Fork Clone the forked repository to a directory of your choice. The example below assumes the GitHub account is niden; replace it with your own account.

git clone [email protected]:niden/cphalcon

3. Build the Environment Navigate to the cphalcon folder (or your chosen repository location) and build the containers with the following command:

docker compose build 

This process may take some time, depending on your machine’s specifications. It is not required frequently, only when changes occur in the dockerfiles or when you choose to rebuild your containers.

Starting the Environment

Once all the containers have been built, initiate the environment using the following command:

docker compose up -d

The above command, utilizing the docker-compose.yml file from the repository, runs the environment in the background, allowing you to reuse your terminal. To stop the environment, press Ctrl-C if the -d flag was not used. If -d was used, inform Docker that you wish to halt the environment:

docker compose down

Environment Configuration

Exposed Ports

With the above command, service containers expose ports to your host as detailed in the table below:

This setup is convenient for most developers. However, for those concurrently working on multiple projects using the same services (e.g., mysql), this configuration may hinder a second environment’s functionality, as the port on the host is already in use.

Isolated Configuration

Alternatively, use the docker-compose-local.yml file, which does not expose ports from service containers to the host, ensuring isolation:

docker compose -f docker-compose-local.yml up -d

In this case, you’ll need to determine the IP address of a specific service container to connect to it. For example, to connect to the mysql container:

docker inspect \
  -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' \
  cphalcon-mysql

Identify the correct IP address and connect accordingly:

mysql -uroot -p -h172.18.0.4

Entering the Environment

To enter the environment, specify the desired PHP version environment. Three environments are available:

cphalcon-8.0 cphalcon-8.1 cphalcon-8.2

For example, to enter the PHP 8.1 environment:

docker exec -it cphalcon-8.1 /bin/bash

You’ll be prompted with:

root@cphalcon-81:/srv#

You are now inside the environment with all the necessary extensions and services. To exit, type exit and press Enter:

root@cphalcon-81:/srv# exit

Aliases

The development environments include predefined aliases in the .bashrc file located under the docker/ folder and the corresponding PHP version subfolder. Some notable aliases include:

Composer

Before proceeding, update Composer:

root@cphalcon-81:/srv# composer install

Composer commands

Composer is configured to facilitate testing. Execute the commands as follows:

composer <command>

Example:

# Run the code sniffer
composer cs

Check Zephir

Zephir is installed by composer. Ensure that the latest version is installed by executing:

root@cphalcon-81:/srv# zephir

The output should resemble the formatted screen provided in the documentation.

Compile Phalcon

Compile Phalcon using Zephir:

root@cphalcon-81:/srv# cpl

Check Extensions

Verify that extensions are correctly installed by typing:

root@cphalcon-81:/srv# php -m

Check for phalcon in the list of installed modules.

Setup Databases

Create a .env file in the project root:

root@cphalcon-81:/srv# cp tests/_config/.env.docker .env

Running Tests

Unit

Build the Codeception base classes before running unit tests:

root@cphalcon-81:/srv# codecept build

Run unit tests:

root@cphalcon-81:/srv# test-unit

Execute tests from a specific folder:

root@cphalcon-81:/srv# codecept run tests/unit/some/folder/

Execute a single test:

root@cphalcon-81:/srv# codecept run tests/unit/some/folder/some/test/file.php

Database

Run database-related tests using aliases:

root@cphalcon-81:/srv# test-db-common
root@cphalcon-81:/srv# test-db-mysql
root@cphalcon-81:/srv# test-db-pgsql
root@cphalcon-81:/srv# test-db-sqlite
root@cphalcon-81:/srv# test-db       

Development

Open your preferred editor and start developing in Zephir. For any changes to .zep files (inside the phalcon folder), recompile the extension:

root@cphalcon-81:/srv# cpl

Run tests after making changes:

root@cphalcon-81:/srv# codecept run tests/unit/somefolder/somecestfile:sometest

For Zephir documentation, refer to the Zephir Docs site.

Services

The available services are:

• Memcached
• MySQL
• PostgreSQL
• Redis

Enabled PHP extensions include:

• apcu
• ctype
• curl
• dom
• fileinfo
• gd
• gmp
• gettext
• imagick
• iconv
• igbinary
• intl
• json
• memcached
• mbstring
• mongodb
• opcache
• phar
• pdo
• pdo_mysql
• pdo_pgsql
• pdo_sqlite
• redis
• session
• simplexml
• sqlite3
• tokenizer
• yaml
• zephir_parser
• xdebug
• xml
• xmlwriter
• zip
• zlib

Database dumps are located under tests/_data/assets/schemas

For questions, join the Discord server or our Discussions.

<3 Phalcon Team