How to build a site with HarmonyCMS

Following the first article I wrote to introduce HarmonyCMS as a Symfony 4 CMS, I will now try to explain to you how to proceed to build a website with the packages provided by HarmonyCMS.

This is currently a beta version, licensee acknowledges that application is prerelease code and is subject to change. Using this software in production is hardly not recommended due to it’s instability.
You can find a full list of which features contain this first beta version in here.

Docker support

HarmonyCMS skeleton repository includes preconfigured docker and docker-compose files. This skeleton provide a fully configured docker environment with the next configured services: php, nginx, MariaDB and MongoDB.

If you choose to use the built-in Docker configuration, follow the instructions in this README.md file. However, you will probably adapt some commands described in this article.

Initiate a new HarmonyCMS project

To create your new HarmonyCMS project, first make sure to fulfill the requirements and have Composer installed. If not, start by installing Composer globally on your system.

Now, create your new HarmonyCMS project by running:

composer create-project harmony/skeleton demo

During the installation process, Composer will ask you to provide an OAuth2 Access Token.
Head to https://account.harmonycms.net/settings/api to retrieve your token.

DO NOT fill the ProjectID during the installation process.
Due to some issues with HarmonyFlex plugin, your installation will be broken!

This will create a new demo directory, download all needed dependencies into it and generate the basic HarmonyCMS structure directories and files you'll need to have a complete functional project.

To check if your new website site is ready, you can now go to the next URL: http://localhost:8080

You should view a page like that.

Choose your database type

HarmonyCMS is currently supporting SQL and No-SQL databases. To do that, this CMS is fully decoupled from any database system.
This means, you will have to choose between SQL and No-SQL.

Such has Symfony, HarmonyCMS doesn’t provide a component to work with the database, but it does provide tight integration with a third-party library called Doctrine.

SQL

You will need to install the emulienfou/orm-pack if your database server is one of MySQL, MariaDB, Oracle, Microsoft SQL Server, PostgreSQL, SAP Sybase SQL Anywhere, SQLite or Drizzle by executing the next command:

composer require emulienfou/orm-pack

This pack provides 2 virtual packages who can be used to require a doctrine database support:

• doctrine/implementation
• doctrine/orm-implementation

The database connection information is stored as an environment variable who will need to be configured in the .env file:

# customize this line!
DATABASE_URL="mysql://db_user:db_password@127.0.0.1:3306/db_name"

# to use sqlite:
# DATABASE_URL="sqlite:///%kernel.project_dir%/var/app.db"

Now that your connection parameters are setup, Doctrine can create the db_name database for you. Execute the next command to create the database:

php bin/console doctrine:database:create

No-SQL

If your database server is MongoDB, you should install the next pack by executing both commands:

composer config “platform.ext-mongo” “1.6.16”
composer require emulienfou/mongodb-pack

This pack provides 2 virtual packages who can be used to require a doctrine database support:

• doctrine/implementation
• doctrine/mongodb-implementation

The database connection information is stored as an environment variables who will need to be configured in the .env file:

MONGODB_URL=mongodb://localhost:27017
MONGODB_DB=symfony

Now that your connection parameters are setup, Doctrine can create the db_name database for you. Execute the next command create the database:

php bin/console doctrine:mongodb:schema:create

Updating recipes

After installing a doctrine database support package (ORM or ODM), you will need to re-apply recipes for the packages who have been provided by the core bundles.

To do that, you will need to execute the next command:

composer sync-recipes --force

You will also need to update the database schema using one of this command:

// For ORM
php bin/console doctrine:schema:update --force
// For ODM
php bin/console doctrine:mongodb:schema:update

Add the user bundle

When you initiate a new HarmonyCMS project, the default skeleton do not provide an user layer either. This layer need to be manually installed so that you can have a user authentication system.

To do that, you will need to install the next UserBundle provided by HarmonyCMS by executing the next command:

composer require harmony/user-bundle

Configure the security layer

For the UserBundle to be able to log in a user, some configuration is necessary to be made to the security layer. You will need to update the file config/packages/security.yaml with the next configuration:

security:
    encoders:
        Symfony\Component\Security\Core\User\UserInterface:
            algorithm: bcrypt
    role_hierarchy:
        ROLE_ADMIN:       ROLE_USER
        ROLE_SUPER_ADMIN: ROLE_ADMIN
    providers:
        user_provider:
            id: Harmony\Bundle\UserBundle\Security\UserProvider
    firewalls:
        main:
            pattern:  ^/
            provider: user_provider
            user_checker: Harmony\Bundle\UserBundle\Security\UserChecker
            anonymous:    true
            form_login:
                login_path: harmony_user_login
                check_path: harmony_user_login
            logout: true
    # Easy way to control access for large sections of your site
    # Note: Only the *first* access control that matches will be used
    access_control:
        - { path: ^/login, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/password-reset, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/lost-password, role: IS_AUTHENTICATED_ANONYMOUSLY }

Update schema

Depending of which database system you have chosen, you will need to execute one of the next command to update your database schema.

If you chose to install the emulienfou/orm-pack , you will need to execute the next command:

php bin/console doctrine:schema:update --force

However, if you chose to install the emulienfou/mongodb-pack , you will need to execute the next one:

php bin/console doctrine:mongodb:schema:update

Register and login to your account

After you finish configuring the UserBundle, you will now be able to register a new user account by going to the next URL: http://localhost:8080/register.

You can also create a new user using the next command line:

php bin/console user:create

When your account has been successfully created, you can proceed to the login page right here: http://localhost:8080/login

Install and enable the skeleton theme

A theme is represented the same way has a Symfony Bundle. Themes are automatically installed by HarmonyFlex tool in the themes directory, at the root of your Harmony’s project.

To install the skeleton theme, you will need to execute the next command:

composer require harmony/acme-theme

To enable the theme manually, create the file config/packages/settings.yaml and add the next configuration:

harmony_settings_manager:
    settings:
        - name: theme
          type: string
          tags: ['theme']
          data: 'HarmonyAcmeTheme'

If you prefer to use the admin bundle to enable your theme, check the next step!

Add the admin bundle

HarmonyCMS do not provide by default an admin interface to manage the CMS and its contents. The particularity of this admin interface is that it support both SQL and No-SQL databases, and came with predefined interfaces to manage the CMS settings, themes and extensions.

If you are intent to use it, you should require the next package:

composer require harmony/admin-bundle

To secure the admin interface, you will need to update your security layer and restrict his access for administrators only.
Edit the config/packages/security.yaml file and add the next configuration:

security:
    access_control:
        // ...
        - { path: ^/admin, roles: ROLE_ADMIN }

However, you will need to promote the user you created before by adapting and executing the next command:

php bin/console user:promote demo@example.com --super

Since the AdminBundle is installed, the templates of the UserBundle are stylized with the admin design like you can see in this next picture.

Installing some extensions

For the beginning of this project, 4 extensions are already available:

Menu manager

The Menu Manager module allow users to easily manage menu and menu items. Menus can be imported from YAML configuration files and are stored in the database. This manager use HarmonyMenuBundle who is on top of KnpMenuBundle.

To install this extension, just run the next command:

composer require harmony/menu-manager

Translation manager

The Translation Manager module allow users to import translation files content into the database and provide a GUI to edit translations.

To install this extension, just run the next command:

composer require harmony/translation-manager

Route manager

The Route Manager module allow users to easily create routes and redirect routes who are saved in database.

To install this extension, just run the next command:

composer require harmony/route-manager

Static page

The Static Page plugin allows end users to create and edit static pages with a simple user interface.

To install this extension, just run the next command:

composer require harmony/static-page

What’s next?

Which features will be included in the next beta release can be found in the next list here: Beta 2 release.

If you find any bugs, you can open a new issue or even send a new pull request in the correct project who can be found right here: HarmonyCMS.

We are currently searching for people who are ready to contribute on this project. If you are interested, you can start by going to the developer documentation.