thecodingmachine/cms-static-registry

A static registry (loads pages from static files) for thecodingmachine/cms-interfaces.

dev-master / 1.0.x-dev 2018-01-04 11:15 UTC

Requires

• php: >=7.1
• mnapoli/front-yaml: ^1.5
• psr/simple-cache: ^1
• symfony/finder: ^3.3 || ^4
• thecodingmachine/cms-interfaces: ^1
• thecodingmachine/cms-utils: ^1
• thecodingmachine/funky: ^1

Requires (Dev)

• mnapoli/simplex: ^0.4.1
• phpunit/phpunit: ^6.2
• satooshi/php-coveralls: ^1.0
• symfony/cache: ^3.3
• thecodingmachine/phpstan-strict-rules: ^0.9

MIT

• David Négrier

README

CMS static registry

Load pages/blocks/themes from static files in your repository.

This package can ban used with the CMS interfaces to build a full-featured PSR-7 CMS.

Why?

Most CMSes out there store content of HTML pages in databases. While there are a number of advantages to do so, this also comes with some drawbacks:

This package is a "file store". It proposes to store files, blocks, themes, etc... into static files instead.

Files have a number of advantages over databases:

• They can be committed in your code repository
• Therefore, it is easy to migrate content from a test environment to a production environment (content is part of your code)
• It is also easy to keep track of history (using your favorite VCS like GIT)
• You can easily work as a team on some content and use branching and merging capability of your VCS to manage content

Of course, this is no silver bullet and using a database to store content can make a great deal of sense. But for content that is mostly administered by a technical team, storing content in files instead of a database is a breeze of fresh air.

Directory structure

Your website will typically be stored in directory of your project.

The default proposed directory structure is:

• cms_root
  • pages
    • a_page.html
    • another_page.md
  • blocks
    • a_block.html
    • another_block.md
  • themes
    • my_theme
      • index.twig
      • config.yml
      • css/
      • js/
      • ...
  • sub_themes
    • a_subtheme.yml
    • another_subtheme.yml

Pages

A page is... well... it's a page of your website! Pages can be:

• in HTML (if the extension is .html)
• in Markdown (if the extension is .md)

Pages come with a YAML frontmatter.

Here is a sample page:

---
url: hello/world
website : example.com
lang : fr
title : foo
theme : foo_theme
meta_title : bar
meta_description : baz
menu : menu 1 / menu 2 / menu 3
menu_order : 1
---

<h1>Hello world!</h1>

The YAML frontmatter MUST be surrounded by ---.

Parameters of the YAML Frontmatter:

Name	Compulsory	Description
url	Yes	The URL of the page. It contains only the path. For instance: /foo/bar
website	No	The domain name of the page. For instance: example.com
lang	Yes	The language of the page, on 2 characters. For instance: "en", "fr"...
title	Yes	The title of the page (goes into the <title> HTML tag
theme	No	The theme (or sub-theme) of the page (more about themes below)
id	No	A unique ID for the page
menu	No	The menu item. The path to the menu item is separated by '/'. For instance: 'Products / Food / Bananas'
menu_order	No	The priority of the menu item
menu_css_class	No	An optional CSS class to be applied to the menu item
meta_title	No	The title <meta> tag
meta_description	No	The description <meta> tag
theme	No	The theme to be used for this page
template	No	The path to the Twig template applied for this page. Relative to the theme root directory. For instance: "blog.twig"
context	No	An array of values passed to fill the Twig template.
inherits	No	A reference to a YAML file that contains default values for the page. For instance: "../page_defaults.yml"

TODO: continue documentation