macrominds/website-lib

Library for simple Websites based on plain Markdown files with YAML frontmatter

v1.0.0 2023-09-17 09:43 UTC

README

Use this simple framework to create websites with:

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.

The docker images inherit macrominds/app php.df. Both docker files use build args for composer- and php versions.

To build the docker images locally:

$ ./ci.bash build-all-local

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
$ docker run -it --rm -v $(pwd):/var/www/html macrominds/website-lib:php80 vendor/bin/phpunit

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

$ ./ci.bash build-all-remotes-and-publish

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.