ceus-media / hydrogen-framework
Installs: 2 714
Dependents: 4
Suggesters: 0
Security: 0
Stars: 1
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: ^7.4 | ^8
- ext-json: *
- ext-pdo: *
- ceus-media/cache: *
- ceus-media/common: ^0.9 | ^1.0 | 0.9.x-dev | 1.0.x-dev
- ceus-media/database: ^0.5 | ^0.6 | 0.5.x-dev | 0.6.x-dev
- ceus-media/template-engine: dev-master
Requires (Dev)
- ceus-media/doc-creator: *
- php-parallel-lint/php-parallel-lint: ^1.3 | dev-master
- phpstan/phpstan: ^1
- phpstan/phpstan-strict-rules: ^1
- phpunit/phpunit: ^9
- rector/rector: *
- dev-master
- 1.0.x-dev
- 0.9.x-dev
- 0.9.1
- 0.9.0
- 0.8.x-dev
- 0.8.8.1
- 0.8.8.0
- 0.8.7.9
- 0.8.7.8
- 0.8.7.7
- 0.8.7.6
- 0.8.7.5
- 0.8.7.4
- 0.8.7.3
- 0.8.7.2
- 0.8.7.1
- 0.8.7
- 0.8.6.9
- 0.8.6.8
- 0.8.6.7
- 0.8.6.6
- 0.8.6.5
- 0.8.6.4
- 0.8.6.3
- 0.8.6.2
- 0.8.6.1
- 0.8.6
- 0.8.5.7
- 0.8.5.6
- 0.8.5.5
- 0.8.5.4
- 0.8.5.3
- 0.8.5.2
- 0.8.5.1
- 0.8.5
- 0.8.4.9
- 0.8.4.8
- 0.8.4.7
- 0.8.4.6
- 0.8.4.5
- 0.8.4.4
- 0.8.4.3
- 0.8.4.2
- 0.8.4.1
- 0.8.4
This package is auto-updated.
Last update: 2024-11-04 02:53:28 UTC
README
A PHP application framework using MVC, with design patterns and modules.
This application framework for PHP is a simple yet powerful engine to develope custom web applications in MVC style.
A created frame (=empty application with framework and depencies) can be filled with life by installing modules from existing module sources or create you own module.
Installation
Create a project folder, step into it and create a composer project:
mkdir myProject
cd myProject
composer init
You need composer to be installed. If not, install composer globally or locally and run composer init
or ./composer.phar init
Answer all information questions and skip definition of requirements.
Once done, include the framework:
composer require ceus-media/hydrogen-framework
There are three branches, for more information see Appendix.
Hymn
To be able to manage your project using the framework and its modules, you will need the CLI tool "hymn".
You can install hymn:
- globally on your server
- locally as a standalone tool within your project root folder
- as project dependency in development mode
Globally
sudo curl -LsS https://github.com/CeusMedia/Hymn/raw/master/hymn.phar -o /usr/local/bin/hymn
sudo chmod a+x /usr/local/bin/hymn
hymn version
As local standalone
curl -LsS https://github.com/CeusMedia/Hymn/raw/master/hymn.phar -o hymn
chmod a+x hymn
./hymn version
As project dependency
composer require ceus-media/hymn
./vendor/bin/hymn version
So, the hymn CLI command will differ depending on your installation type:
hymn COMMAND [PARAMETERS]
(globally)./hymn COMMAND [PARAMETERS]
(local standalone)vendor/bin/hymn COMMAND [PARAMETERS]
(project dependency)
Hydrogen project
Now, create a hydrogen project using hymn:
hymn create
Answer all information questions. Provide database credentials to access or even create a database. Skip configuration of composer since you already have this step. Skip configuration of PHPUnit for now.
You now have the hydrogen project file .hymn
.
This file will extend in the process and holds all information needed to (re-)install a constallation of defined and configured modules from defined sources.
Add local module source
mkdir modules
hymn source-add
Enter:
- Source ID: ENTER
- Source type: ENTER
- Source path:
modules
- Source description:
Local project modules.
Add public modules of Ceus Media
To make use of existing modules to play around or, later, create real applications, you can use the public modules of Ceus Media. This module source contains about 300 modules, structured by category.
Install this library and register it as module source:
composer require ceus-media/hydrogen-modules
hymn source-add
Enter:
- Source ID:
CeusMedia_Public
- Source type: ENTER
- Source path:
./vendor/ceus-media/hydrogen-modules/
- Source description:
Public module library maintained by Ceus Media.
Source check
Now, if you are running:
hymn source-list
you can see the registered and indexed module sources.
There should be the two Local_Modules
and CeusMedia_Public
.
Both sources are marked as active, so they are taken into account by hymn.
The default source is the first one created. In this case Local_Modules
.
Installing a module will prefer the default source, if not specified otherwise.
Installing modules
Module categories
In the world of Hydrogen modules, there a several types of modules called category. Some module are very small and just provide one JavaScript file.
Others are complex and deliver:
- views, maybe with forms and style definitions
- language file (aka localization)
- mails, if mails need to be send
- jobs, to be executed via CLI or cron tab
- HTML blocks to customer views and explain things . JavaScript, for dynamics with web views
- much more
Such rich modules are there to:
- collect or manage module contents (mostly structured in a database)
- provide connections to resources (for storing and reading of contents)
- display collected contents in web views
App modules combine several modules together to an executable web application. This may include:
- an e-mail queue and archive
- job execution via CLI
- job automation via cron
- request tracking
- user authentication
Having a functional application, you can extend functionality by:
- using further modules other
- creating own modules
- export your own modules to your own module source
- use modules from your own module source
You can list available modules:
hymn modules-available [SOURCE_ID]
Display (all) details of a module:
hymn module-info [MODULE_ID] -v(v)
Install a module and uninstallation:
hymn app-install [MODULE_ID]
hymn app-uninstall [MODULE_ID]
Application
For this example, we will use the app module App_Site
:
hymn app-install App_Site
This will install a boilerblate web application with:
- Basic Layout: default master template of some HTML blocks for header and footer etc.
- Module
UI_Bootstrap
: CSS framework Bootstrap. - Module
JS_jQuery
: JavaScript framework JQuery. - Some exception handling system components.
The CSS framework Bootstrap comes with the icon set of Font Awesome and installs:
- Module
UI_Font
: a general font manager. - Module
UI_Font_FontAwesome
: Font Awesome integration.
One of the system components (a logger) can be configured to send e-mails on errors. Therefore a module capapble of sending mails will be installed automatically.
Since the sending of mails will by handled by a CLI script (to be decoupled from the web application), a mail queue will be introduced to a database and a job handling mechanism will be installed:
- Module
Resource_Mail
: a mail generator, queue and sender - Module
Resource_Jobs
: a manager to execute module jobs via CLI or cron job
Finally
Create a logs folder and allow the web server to write to it. Could look like:
mkdir logs
sudo chrp www-data
sudo chmod ug+w logs
Now, open the project URL in a browser.
Sandbox application
If the installation is too much for you right now, you could checkout a simple sandbox installation.
Clone an empty application skeleton:
composer create-project ceus-media/hydrogen-app -n
Afterwards change into project folder and run setup for development:
cd hydrogen-app && make set-install-mode-dev
Create an empty database on your server, and maybe a database user beforehand.
Now you are ready to install application modules:
make install
Appendix
The three branches
- Branch dev-master should be stable
- Branch 0.8.x aka dev-master is recommended, since all modules are for this version.
- Branch 0.9.x is experimental stage (including namespaces).
- If all modules are compatible to 0.9.x, dev-master will step from 0.8.x to 0.9.x.
Installing branches
Latest stable development (dev-master), current on 0.8.x:
composer require ceus-media/hydrogen-framework
Latest 0.8.x current development branch:
composer require ceus-media/hydrogen-framework:^dev-0.8-x
Latest 0.9.x future development branch:
composer require ceus-media/hydrogen-framework:^dev-0.9-x
Module sources
A module source is a library of one or more modules. This library could be a GitHub repository, packaged by packagist and installable using composer Or any other online Git repository, shared or private.
Event System
Besides the usual Request->Dispatch->Render->Response behavior, a event system exists to inject module code with the bootstrap process. Therefore events can be attach on hooks, which will be called by the system during boot or later within modules.
Default Hook Calls
These hooks will be called by the system during boot:
- Env::initModules
- Env::initDatabase
- Database::init
- Env::initCache
- Session::init
- Page::init
- Page::applyModules
- Env::constructEnd
- Env::init
- App::onControl
- App::onDispatch
- Controller::onDetectPath
- Page::build
- App::respond