Heroyt's PHP Framework

Author: Tomáš Vojík <vojik@wboy.cz>

Web: laserliga.cz

Directory structure

• assets - frontend files go here
  • scss - all css files
  • js - all js files
• config - Configuration files
• docs - generated documentation - html
• include - core PHP files
• languages - translation files (gettext)
• logs - log files
• private - Hidden configuration files (db connection)
• routes - Route definitions
• src - main app source files: \App namespace
  • Controllers - Defined controllers
  • Core - App\Core namespace
  • Exceptions - Custom exceptions
  • Models - Defined models
  • Logging - Logger
  • Tools - Other helper classes
• temp - temporary files generated by the app
• templates - Latte templates
• tests - Unit tests
• vendor - libraries

Code conventions

• PHP version - 8.0^
• Charset - UTF-8
• Line break - Unix
• Indent - Tab
• Tab size - 4
• Variable naming scheme - camelCase
• Constant naming scheme - UPPERCASE_SNAKE_CASE
• Function naming scheme - camelCase
• Function / method declaration

  function functionName(...$arg) {
    // Code
  }

• PHP array - [...]

Git conventions

Commit message guide:

See: Gitmoji

• ⬆️ - Update dependencies
• 🎨 - Formatting update
• ⚡️ - Performance update
• 🔥 - Code or file deletion
• 🐛 - Bugfix
• 🚀 - Deploy next version
• ✅ - Testing
• 💄 - Style and visual update
• ♻️ - Refactor code
• 📄 - Documentation or license update

Used libraries

All libraries are installed using Composer.

• Dibi - database connection library
• Nette - Utils, Caching, Safe-stream, Mail
• Latte - Templating
• Tracy - Debugging and logs
• PHPUnit - Unit testing PHP
• Tournament generator

Front end libraries

• Webpack
• Bootstrap
• Axios - AJAX library
• FlatPickr - Date (and time) picker

Installation

First, you need to set up the app's config file.

Copy the /private/config_dummy.ini file to /private/config.ini and change the necessary DB connection configuration.

Then, install the application by calling:

$ composer install-app

This will install all dependencies, build webpack assets (css and js), create all DB tables and seed it with starting data.

Lastly, you can start the PHP server with:

$ composer serve

(You don't have to start the server if you have Apache setup already)

Tools

Generate docs

Docs are written as phpdoc / doxygen style comments and generated using Doxygen.

$ doxygen

$ composer docs

Other

$ composer build

Installs composer dependencies, installs npm dependencies, builds webpack assets.

$ composer build-production

Installs composer dependencies, installs npm dependencies, builds webpack assets and removes dev-dependencies.

$ composer install-app

Runs composer build and installs database - creating DB tables and seeding some data.

$ php install.php [fresh]

Installs database - creating DB tables and seeding some data. If argument fresh is given, current tables are dropped and the database is cleared before installing.

$ composer test

Runs unit tests.

$ composer serve

Starts PHP server on port 8000.

$ composer docs

Generates doxygen API docs.

$ npm run build

Builds webpack assets in production mode.

$ npm run build-dev

Builds webpack assets in development mode.

$ npm run watch

Builds webpack assets. Watches assets changes and auto-builds on save.

PHP

All libraries are installed using Composer.

$ composer install

Front-end

Front-end dependencies are managed by npm and Webpack .

Download npm and Node.js

Install all npm packages:

$ npm install

Run webpack (pack all js and css)

$ npm run build

Run tests

PHPUnit is installed as a developer dependency using ** Composer**.

$ composer test

Templating

All pages have a defined class in App\Controllers namespace containing all logic, and a latte template file containing all HTML in templates folder.

Custom Latte tags and filters are defined in config/latte.php.

@link pages-page Pages creation documentation @endlink

Translation

There are 3 ways of translating text in latte templates.

Function - also available in all PHP code

{lang('Text to translate')}

Filter

{$variableToTranslate|lang}

Tag

{lang 'Text to translate'}

Links

There is also a Latte alternative to App::getLink method

{link ['path', 'to', 'parse', 'param' => 'value']}

{getUrl}

Returns a base (root) URL of the site.

CSRF

Cross-site-scripting protection is implemented using latte helper functions.

{csrf}

Returns a general purpose CSRF token.

{csrfInput $name}

Returns a generated html input[type=hidden] containing a CSRF token. $name is preferably the name of the form, or any other identifier.

Validating CSRF

isTokenValid($hash);

Checks if the given hash is valid.

formValid($name);

Checks if hash for sent form exists and is valid.

Using CSRFCheck middleware

Middleware can be attached to a Route or Controller on setup. CSRFCheck middleware checks if there is a valid CSRF token and returns an error otherwise. CSRF form name is equal to route's path.

Example:

// routes/web.php

use \App\Core\Routing\Route;
use \App\Controllers\Test;
use \App\Core\Middleware\CSRFCheck;

Route::get('/test', [Test::class, 'show']);
Route::post('/test', [Test::class, 'send'])->middleware(new CSRFCheck());

// src/Controllers/Test.php

namespace \App\Controllers;

use \Lsr\Core\Requests\Request;

class Test extends \Lsr\Core\Controller {
	
	public function show() {
		$this->view('pages/test/index');
	}
	
	public function send(Request $request) {
		// Process form here
		$this->view('pages/test/index');
	}

}

{* templates/pages/test/index.latte *}
{layout '../../@layout.latte'}

{define content}
<form action="{link ['test']}">
	{csrfInput 'test'}

	{* Rest of the form here... *}

	<button type="submit">Send</button>
</form>
{/define}