Download the PHP package ceus-media/hydrogen-framework without Composer

HydrogenFramework

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:

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:

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

As local standalone

As project dependency

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:

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

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:

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:

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:

Display (all) details of a module:

Install a module and uninstallation:

Application

For this example, we will use the app module 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:

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:

Afterwards change into project folder and run setup for development:

Create an empty database on your server, and maybe a database user beforehand.

Now you are ready to install application modules:

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:

Latest 0.8.x current development branch:

Latest 0.9.x future development branch:

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