Download the PHP package omegamvc/omega without Composer

Documentation | Changelog | Contributing | Code Of Conduct | License

Omega Framework: Example Application Overview

This is an example application built with the Omega framework. Visit the official Omega website to learn more about its structure, controllers, models, views, and features.

System Requirements

To successfully run this application, ensure you meet the following requirements:

• PHP Version: 8.2 or later
• Web server: Apache 2.4 or later with mod_rewrite enabled
• Database: MySQL 8.0+, MariaDB 10.5+, or SQLite3

Example Application Structure

In this section, we will explore the structure of the example application provided with Omega. Understanding the organization of the project's directories and files will help you navigate and customize the application effectively. Below is a breakdown of each folder's purpose within the example application.

Installing Example Application

Install Omega by running the following command:

This command does not download the dependencies listed in require-dev due to the .gitattributes settings. If you want to work with the complete source code, consider the options below.

Cloning the repository

If you prefer to work directly with the full source code, clone the repository:

After cloning, install all dependencies, including development ones, with:

Option --prefer-source

If you want to install the project while keeping the source code and dependencies for easier debugging or development, use the --prefer-source option:

Configuration

The example application offers several areas where its behavior can be customized. All these customizations can be found in the config folder.

In this section, we will review the most important ones.

Customizing the Cache Configuration

The config/cache.php file lets you define how caching works in your application.

The configuration array is structured as follows:

Here's what each parameter means:

• default: (Default: file) Specifies the currently selected cache driver.
• seconds: Allows you to set the cache expiration time in seconds.
• path: Lets you specify an alternative path where the cache will be stored.
• host: Specifies the server where Memcached is running.
• port: Specifies the port where Memcached is listening.

All configuration parameters can be overridden using the .env file.

Example of custom cache path:

Setting Up the Database

The config/database.php file allows you to configure the database engine you want to use and in the case of sqlite3, specify a file to use as the database.

The configuration array is structured as follows:

Here's what each parameter means:

• default: (Default: mysql) Specifies the default database engine to use.
• host: Allows you to specify the server where the database engine is running.
• port: Lets you specify a port other than the default one where the database engine is listening.
• database: Specifies the name of the database to use.
• username: This is the username for accessing the database.
• password: This is the password for accessing the database.

All configuration parameters can be overridden using the .env file.

Example of custom database path:

Once configured, create tables and populate them with sample data using:

To delete all tables and data, run:

Note that the composer db_fresh command is irreversible and will destroy all data, including tables and restoring the default contents.

In the case of mysql/mariadb, the database will be created automatically, and there is no need to create it manually.

Analysis

Static Code Analysis with PHPStan

To run static analysis with PHPStan, use the command:

Static Code Analysis with Code Sniffer

To check the code with Code Sniffer, run the command:

Generating API Documentation with phpDocumentor

To generate the documentation, run the command.

Make sure you have the phpDocumentor.phar 3.5+ executable installed in the vendor/bin directory.

Testing

Running Unit Tests with PHPUnit

To run the tests with PHPUnit, type the command:

Note that the command above will run tests for the classes contained in the app and vendor/omegamvc directories.

Generating Code Coverage Reports

Omega supports code coverage with, requiring xdebug to be installed and configured on your system.

Here’s a basic working xdebug configuration for Ubuntu 24.04:

In accordance with the phpunit documentation, you should also ensure that the error_reporting and memory_limit variables are set as follows in the /etc/php/your_php_version/cli/php.ini file:

For more information, you can refer to the official documentation of phpunit

Using the PHP Built-In Server with Omega

Omega has a script that starts the built-in PHP server. However, please note that due to the absence of pcntl extensions, the verbosity level on Windows operating systems is lower than that on Linux and MacOSX.

The serve command can be customized by modifying the .env file:

Alternatively, you can pass the address and port of your server to the serve command.

Additional Configuration and Setup Notes

Setting Up Nginx for Omega

The follow is a simple configuration per nginx

Where:

• root: Sets the path to the public directory of your Omega project, which contains the index.php file.
• try_files: Ensures that all requests are handled by the index.php file if no matching file is found, as is typical in an MVC application
• fastcgi_pass: Instructs Nginx to forward PHP requests to the PHP-FPM server. Make sure the PHP-FPM socket path (php8.x-fpm.sock) matches the PHP version installed on your system.
• location ~ /.ht: Prevents access to .htaccess files, which are not needed in Nginx but may still be present.

This configuration serves as a good starting point for both development and production environments. If needed, you can add further settings for security, performance, or other project-specific needs.

Troubleshooting and Known Issues

PHPCS (Code Sniffer)

The phpcs.xml.dist file is preconfigured to save the cache in the cache/phpcs directory at the root of the project. If this directory does not exist, Code Sniffer cannot create it automatically, and you will need to create it manually.

To disable the cache, you can simply comment out or remove this line from the phpcs.xml.dist file.

If you prefer to choose a custom path that better suits your habits, you can simply modify it.

Errors When Running Commands from the Console

All commands defined in the composer.json file are prefixed with the variable XDEBUG_MODE=off. This prevents xdebug from producing an excessive amount of output if the configuration is set to xdebug.mode=debugor xdebug.mode=debug,develop. If you run commands that are not defined in the composer.json file, you can suppress these messages as follows:

Official Documentation

The official documentation for Omega is available here

Contributing

If you'd like to contribute to the Omega example application package, please follow our contribution guidelines.

License

This project is open-source software licensed under the GNU General Public License v3.0.