{"id":22954911,"url":"https://github.com/omegamvc/omega","last_synced_at":"2025-04-16T05:51:27.300Z","repository":{"id":276487991,"uuid":"924352517","full_name":"omegamvc/omega","owner":"omegamvc","description":"Omega is a lightweight PHP framework designed for building modern web applications using the MVC architecture.","archived":false,"fork":false,"pushed_at":"2025-03-01T12:22:31.000Z","size":103,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T05:04:42.433Z","etag":null,"topics":["example-app","framework","lightweight","modern","mvc","php","php8","php82","web"],"latest_commit_sha":null,"homepage":"https://omegamvc.github.com","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/omegamvc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-29T21:05:40.000Z","updated_at":"2025-03-01T12:22:03.000Z","dependencies_parsed_at":"2025-02-16T14:37:23.337Z","dependency_job_id":null,"html_url":"https://github.com/omegamvc/omega","commit_stats":null,"previous_names":["omegamvc/omega"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omegamvc%2Fomega","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omegamvc%2Fomega/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omegamvc%2Fomega/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/omegamvc%2Fomega/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/omegamvc","download_url":"https://codeload.github.com/omegamvc/omega/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249205023,"owners_count":21229848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["example-app","framework","lightweight","modern","mvc","php","php8","php82","web"],"created_at":"2024-12-14T16:19:54.679Z","updated_at":"2025-04-16T05:51:27.292Z","avatar_url":"https://github.com/omegamvc.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://omegamvc.github.io\" target=\"_blank\"\u003e\n        \u003cimg src=\"https://github.com/omegamvc/omega-assets/blob/main/images/logo-omega.png\" alt=\"Omega Logo\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://omegamvc.github.io\"\u003eDocumentation\u003c/a\u003e |\n    \u003ca href=\"https://github.com/omegamvc/omegamvc.github.io/blob/main/README.md#changelog\"\u003eChangelog\u003c/a\u003e |\n    \u003ca href=\"https://github.com/omegamvc/omega/blob/main/CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e |\n    \u003ca href=\"https://github.com/omegamvc/omega/blob/main/CODE_OF_CONDUCT.md\"\u003eCode Of Conduct\u003c/a\u003e |\n    \u003ca href=\"https://github.com/omegamvc/omega/blob/main/LICENSE\"\u003eLicense\u003c/a\u003e\n\u003c/p\u003e\n\n# Omega Framework: Example Application Overview\n\nThis is an example application built with the Omega framework. Visit the official [Omega](https://omegamvc.github.io) website to learn more about its structure, controllers, models, views, and features.\n\n## System Requirements\n\nTo successfully run this application, ensure you meet the following requirements:\n\n- **PHP Version**: 8.2 or later\n- **Web server**: Apache 2.4 or later with `mod_rewrite` enabled\n- **Database**: MySQL 8.0+, MariaDB 10.5+, or SQLite3\n\n## Example Application Structure\n\nIn 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.\n\n```sh\nomega\n├─ app                          # Contains the core application logic.\n│  ├─ Exceptions                # Custom exceptions for handling errors in the application.\n│  ├─ Http                      # Contains HTTP-related logic such as controllers, middleware, and requests.\n│  │  └─ Controllers            # The controllers that handle HTTP requests and return responses.\n│  └─ Models                    # Contains the models, which represent the data structure and business logic.\n├─ bootstrap                    # Contains the files for bootstrapping the application.\n├─ config                       # Configuration files for the application (e.g., database, services).\n├─ database                     # Contains database-related files such as migrations and seeds.\n│  ├─ migrations                # Database migration files for setting up and modifying the database schema.\n│  │  └─ schemes                # Database schema definitions, typically the tables and their structure.\n│  └─ sqlite                    # Database-related files specific to SQLite (if used).\n├─ public                       # Publicly accessible files (e.g., front-end assets and entry point).\n├─ resources                    # Contains resource files such as views, assets, and localization files.\n│  ├─ images                    # Image files used by the application.\n│  └─ views                     # Templates or view files used to render HTML pages.\n├─ routes                       # Contains route definitions that map URLs to application logic.\n├─ storage                      # Directory for application-generated files (e.g., logs, cache, uploaded files).\n│  ├─ app                       # Application-specific storage (e.g., user-uploaded files).\n│  ├─ framework                 # Framework-generated storage files (e.g., cache, sessions, views).\n│  │  └─ data                   # Internal data storage for the framework.\n│  │     ├─ cache               # Cached data to improve performance.\n│  │     └─ views               # Compiled view files to speed up rendering.\n│  └─ logs                      # Log files generated by the application.\n└─ tests                        # Contains unit and feature tests for the application.\n\n```\n\n## Installing Example Application\n\nInstall **Omega** by running the following command:\n\n```sh\ncomposer create-project omegamvc/omega omega\n```\n\n\u003e 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.\n\n### Cloning the repository\n\nIf you prefer to work directly with the full source code, clone the repository:\n\n```sh\ngit clone https://github.com/omegamvc/omega.git\n```\n\nAfter cloning, install all dependencies, including development ones, with:\n\n```sh\ncomposer install\n```\n\n### Option --prefer-source\n\nIf you want to install the project while keeping the source code and dependencies for easier debugging or development, use the --prefer-source option:\n\n```sh\ncomposer create-project omegamvc/omega omega --prefer-source\n```\n\n## Configuration\n\nThe example application offers several areas where its behavior can be customized. All these customizations can be found in the `config` folder.\n\nIn this section, we will review the most important ones.\n\n### Customizing the Cache Configuration\n\nThe `config/cache.php` file lets you define how caching works in your application.\n\nThe configuration array is structured as follows:\n\n```php\nreturn [\n    'default'  =\u003e env('CACHE_DRIVER', 'file'),\n    'memory'   =\u003e [\n        'type'    =\u003e 'memory',\n        'seconds' =\u003e env('CACHE_SECONDS', '31536000'),\n    ],\n    'file'     =\u003e [\n        'type'    =\u003e 'file',\n        'seconds' =\u003e env('CACHE_SECONDS', '31536000'),\n        'path'    =\u003e Path::getPath('storage','framework/data/cache'),\n    ],\n    'memcache' =\u003e [\n        'type'    =\u003e 'memcache',\n        'host'    =\u003e env('MEMCACHE_HOST', '127.0.0.1'),\n        'port'    =\u003e env('MEMCACHE_PORT', '11211'),\n        'seconds' =\u003e env('CACHE_SECONDS', '31536000'),\n    ],\n];\n```\n\nHere's what each parameter means:\n\n* `default`: *(Default: **file**)* Specifies the currently selected cache driver.\n* `seconds`: Allows you to set the cache expiration time in seconds.\n* `path`: Lets you specify an alternative path where the cache will be stored.\n* `host`: Specifies the server where Memcached is running.\n* `port`: Specifies the port where Memcached is listening.\n\n\u003e All configuration parameters can be overridden using the `.env` file.\n\nExample of custom cache path:\n\n```php\n'path' =\u003e Path::getPath('your_custom_cache_path', 'your_custom_cache_dir')\n```\n\n### Setting Up the Database\n\nThe `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.\n\nThe configuration array is structured as follows:\n\n```php\nreturn [\n    'default' =\u003e env('DB_CONNECTION', 'mysql'),\n\n    'mysql'   =\u003e [\n        'type'     =\u003e 'mysql',\n        'host'     =\u003e env('DB_HOST', '127.0.0.1'),\n        'port'     =\u003e env('DB_PORT', '3306'),\n        'database' =\u003e env('DB_DATABASE', 'omega'),\n        'username' =\u003e env('DB_USERNAME', 'root'),\n        'password' =\u003e env('DB_PASSWORD', 'vb65ty4'),\n    ],\n    'sqlite'  =\u003e [\n        'type' =\u003e 'sqlite',\n        'path' =\u003e Path::getPath('database', 'sqlite/database.sqlite'),\n    ],\n];\n```\n\nHere's what each parameter means:\n\n* `default`: (Default: **mysql**) Specifies the default database engine to use.\n* `host`: Allows you to specify the server where the database engine is running.\n* `port`: Lets you specify a port other than the default one where the database engine is listening.\n* `database`: Specifies the name of the database to use.\n* `username`: This is the username for accessing the database.\n* `password`: This is the password for accessing the database.\n\n\u003e All configuration parameters can be overridden using the `.env` file.\n\n\nExample of custom database path:\n\n```php\nuse Omega\\Support\\Path;\n\n'path' =\u003e Path::getPath('yout_custom_databae__path', 'your_custom_sqlite_path/database.sqlite')\n```\n\nOnce configured, create tables and populate them with sample data using:\n\n```sh\ncomposer db_migrate\n```\n\nTo delete all tables and data, run:\n\n```sh\ncomposer db_fresh\n```\n\n\u003e Note that the `composer db_fresh` command is irreversible and will destroy all data, including tables and restoring the default contents.\n\n\u003e In the case of `mysql/mariadb`, the database will be created automatically, and there is no need to create it manually.\n\n\n## Analysis\n\n### Static Code Analysis with PHPStan\n\nTo run static analysis with `PHPStan`, use the command:\n\n```sh\ncomposer phpstan\n```\n\n### Static Code Analysis with Code Sniffer\n\nTo check the code with `Code Sniffer`, run the command:\n\n```sh\ncomposer phpcs\n```\n\n## Generating API Documentation with phpDocumentor\n\nTo generate the documentation, run the command.\n\n```sh\ncomposer phpdoc\n```\n\n\u003e Make sure you have the `phpDocumentor.phar 3.5+` executable installed in the `vendor/bin` directory.\n\n## Testing\n\n### Running Unit Tests with PHPUnit\n\nTo run the tests with `PHPUnit`, type the command:\n\n```sh\ncomposer phpunit\n```\n\n\u003e Note that the command above will run tests for the classes contained in the `app` and `vendor/omegamvc` directories.\n\n### Generating Code Coverage Reports\n\nOmega supports code coverage with, requiring `xdebug` to be installed and configured on your system.\n\nHere’s a basic working `xdebug` configuration for `Ubuntu 24.04`:\n\n```sh\n// File name: /etc/php/your_php_version/mods_available/xdebug.ini\n\nzend_extension=xdebug.so       \nxdebug.show_exception_trace=0\nxdebug.mode=coverage\nzend_assertion=1\nassert.exception=1\n```\n\nIn 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:\n\n```sh\nerror_reporting=-1\nmemory_limit=-1\n```\n\nFor more information, you can refer to the official documentation of [phpunit](docs.phpunit.de/en/11.4/installation.html)\n\n## Using the PHP Built-In Server with Omega\n\nOmega 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.\n\n```sh\nphp omega serve\n```\n\nThe `serve` command can be customized by modifying the `.env` file:\n\n```sh\nAPP_HOST=server_name_or_ip\nAPP_PORT=port_number\n```\n\nAlternatively, you can pass the address and port of your server to the serve command.\n\n```sh\ncomposer serve --host=server_name_or_ip --port=port_number\n```\n\n## Additional Configuration and Setup Notes\n\n### Setting Up Nginx for Omega\n\nThe follow is a simple configuration per `nginx`\n\n```sh\nserver {\n    listen 80;\n    server_name example.com;\n\n    root /var/www/your_project_name/public;\n    index index.php index.html index.htm;\n\n    location / {\n        try_files $uri $uri/ /index.php?$query_string;\n    }\n\n    location ~ \\.php$ {\n        include snippets/fastcgi-php.conf;\n        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;\n        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;\n        include fastcgi_params;\n    }\n\n    location ~ /\\.ht {\n        deny all;\n    }\n\n    access_log /var/log/nginx/server_name_access.log;\n    error_log /var/log/nginx/server_name_error.log;\n}\n```\n\nWhere:\n\n* `root`: Sets the path to the public directory of your Omega project, which contains the `index.php` file.\n* `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\n* `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.\n* `location ~ /.ht`: Prevents access to `.htaccess files`, which are not needed in Nginx but may still be present.\n\nThis 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.\n\n### Troubleshooting and Known Issues\n\n#### PHPCS (Code Sniffer)\n\nThe `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.\n\nTo disable the cache, you can simply comment out or remove this line from the `phpcs.xml.dist` file.\n\n```xml\n\u003carg name=\"cache\" value=\"cache/phpcs\" /\u003e\n```\n\nIf you prefer to choose a custom path that better suits your habits, you can simply modify it.\n\n#### Errors When Running Commands from the Console\n\nAll 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=debug`or `xdebug.mode=debug,develop`. If you run commands that are not defined in the `composer.json` file, you can suppress these messages as follows:\n\n```sh\nXDEBUG_MODE=off php omega command_name options\n```\n\n## Official Documentation\n\nThe official documentation for Omega is available [here](https://omegamvc.github.io)\n\n## Contributing\n\nIf you'd like to contribute to the Omega example application package, please follow our [contribution guidelines](CONTRIBUTING.md).\n\n## License\n\nThis project is open-source software licensed under the [GNU General Public License v3.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomegamvc%2Fomega","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fomegamvc%2Fomega","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fomegamvc%2Fomega/lists"}