Testing Environment¶

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.0, 8.1), 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

1. 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

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

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

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

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

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