macrominds website-lib

Use this simple framework to create websites with:

• Twig Templates
• YAML content meta data
• Markdown content

The framework is designed with flexibility in mind, so that it might support other templating engines, meta data and content languages later on. The idea is to be able to replace YAML with json, Markdown with Asciidoctor, Twig with blade and so on.

See the Documentation for setup, usage and customization.

Extending and customization

You can replace the default services (see \Macrominds\AppServiceProvider).

You do this by binding either singletons or multi object factories to the container. This way, you can override the settings or add new bindings.

use Macrominds\App;
use Macrominds\Processing\TemplateEngine\TemplateEngine;
use Symfony\Component\HttpFoundation\Request;

$app = new App(realpath(__DIR__ . '/..'));
$app->getContainer()->singleton(
    TemplateEngine::class,
    function(): TemplateEngine {
        return new MyVeryOwnTemplateEngine();
    }
);
$app->getContainer()->factoryObject(
    Request::class,
    function(): Request {
        return new MyCustomizedRequest(/*…*/);
    }
);

$app->getContainer()->resolve(Request::class)->myCustomRequestMethod();

An example usage is to manually debug a certain Request:

use Macrominds\App;
use Symfony\Component\HttpFoundation\Request;

$app = new App(realpath(__DIR__ . '/..'));

// …

// always request /404.html
$app->getContainer()->factoryObject(Request::class, function() {
    return Request::create('/404.html');
});

Testing this project

Run ./vendor/bin/phpunit to run the tests.

To create a code coverage report, run ./code-coverage-report.sh. You can then visit report/coverage/index.html to view the report.

Automatic testing and docker images

This project provides a .gitlab-ci.yml and thus uses GitLab CI/CD.

To build the images locally:

$ docker build -t macrominds/website-lib:php73 --file ci/php_7.3.df ci
$ docker build -t macrominds/website-lib:php74 --file ci/php_7.4.df ci

Run phpunit inside the container:

$ docker run -it --rm -v $(pwd):/var/www/html macrominds/website-lib:php73 vendor/bin/phpunit
$ docker run -it --rm -v $(pwd):/var/www/html macrominds/website-lib:php74 vendor/bin/phpunit

Build and publish the images for gitlab CI (also see gitlab docs):

$ docker login registry.gitlab.com
$ docker build -t registry.gitlab.com/macrominds/website-lib:php73 --file ci/php_7.3.df ci
$ docker push registry.gitlab.com/macrominds/website-lib:php73
$ docker build -t registry.gitlab.com/macrominds/website-lib:php74 --file ci/php_7.4.df ci
$ docker push registry.gitlab.com/macrominds/website-lib:php74

Code quality

Measure the current code quality with phpmetrics:

$ ./phpmetrics-report.sh

TODO

• Support symfony routes for more sophisticated websites and add individual resource route dynamically when it is requested
• Instead of using <div class="block" markdown="1"> for blocks, it would be better if we would just allow multiple markdown sections in a content file (for example separated by ---)
• See if we can get rid of the standard IntlExtension in Macrominds\TemplateEngine\Builder and make it optional. It requires "ext-intl" and is not needed for every website.
• Observe the lack of activity at erusev/parsedown and erusev/parsedown-extra and decide if we should switch to another lib. thephpleague/commonmark looks like a promising alternative.