Customizing forumify

The forumify platform is built on the shoulders of the Symfony Framework. Anything you can do in Symfony is also possible in a forumify application. A conscious decision was made to not wrap Symfony in some "custom forumify sugar" and to allow developers to interact with the underlying framework as much as possible and only provide abstractions when these are useful and save considerable amounts of time. Anyone who has experience with Symfony will immediately feel at home. With that in mind, we highly recommend getting familiar with the Symfony Framework while working in the forumify platform.

This short guide is a tutorial-style introduction to customizing the forumify platform that covers most of the basic concepts.

There are many different ways of hosting a development version of forumify. We recommend you install the following tools on your host OS:

• Docker (Desktop)

While you could use the forumify docker image to develop, we recommend a local PHP environment:

• PHP
  • Check which version is currently required by forumify here.
  • You also need to install/enable the following extensions: pdo_mysql, intl, zip.
• Composer
• NodeJS
• Symfony CLI

Start by cloning the forumify production template:

$ git clone https://github.com/forumify/forumify-production-template.git forumify-app
$ cd forumify-app

This will be your "application" folder. All commands, instructions,... in this guide will be happening inside of this directory.

If you are planning to develop plugins, this will be your sandbox during development for testing.

If you are building a custom forumify application, you can commit and push all the files that are created to your own git repository. A standard .gitignore will ensure only required files are included. Then later, on your production server, you can clone/pull your repository to update.

Reset git so you can link your own repository later:

$ rm -rf .git
$ git init
$ git add .
$ git commit -m "initial commit"

Before we can run anything, we need to install the project dependencies:

$ composer install
$ npm install --force

This will use the Symfony Flex composer plugin to set up your project with some basic files that are needed to run the platform. These files are unique to your project, and you should commit them to version control.

You need 2 services for development, a MySQL server and an email server. You can also add more services like PHPMyAdmin if required.

Here's an example docker-compose.yml which you can place at your project's root directory.

services:
    mysql:
        image: mysql:8.4
        container_name: mysql
        ports:
            - '3306:3306'
        environment:
            MYSQL_ROOT_PASSWORD: 'root'
        volumes:
            - database_data:/var/lib/mysql
        restart: unless-stopped

    mailcatcher:
        image: schickling/mailcatcher
        container_name: mailcatcher
        ports:
            - '1025:1025'
            - '1080:1080'
        restart: unless-stopped

volumes:
    database_data:

Start your dependencies:

docker compose up -d

Inside your project, you will find a .env file with some preset environment variables. We'll want to override some for local development.

Create a .env.local file and modify the values to match your setup. The example below should work with the docker-compose example from earlier when running on Docker Desktop.

APP_ENV=dev
APP_DEBUG=1
APP_SECRET=not-a-real-secret
DATABASE_URL="mysql://root:root@host.docker.internal:3306/forumify?serverVersion=8.0.32&charset=utf8mb4"
MAILER_DSN=smtp://host.docker.internal:1025

We can use the following commands to prepare our database:

$ symfony console doctrine:database:create
$ symfony console doctrine:migrations:migrate

This will create the database specified in our .env.local file, and the migrations will add all tables and basic data required to run forumify.

Once all of your dependencies are ready, you can start your webserver and file watcher:

$ symfony server:start -d
$ npm run watch

If everything went well, you should now have a development instance of forumify running on localhost:8000.

If you followed the recommendation to learn Symfony first, then this development setup for forumify should feel very familiar to you. This was done on purpose so anyone with experience in the Symfony framework can jump straight in.

The next time you want to start your project, all you need to do is start docker (When using Docker Desktop your project should be visible in the GUI too), run your webserver, and start the webpack asset watcher.

$ docker compose up -d
$ symfony server:start -d
$ npm run watch

# Symfony HTTP Server config for local development
workers:
  npm_encore_watch:
    cmd: ['npm', 'run', 'watch']
  messenger_consume_async:
    cmd: ['symfony', 'console', 'messenger:consume', 'async']

In the following guides we will be creating a small TODO application inside forumify by using some of the platform's helpers to speed us up. Our goal will be to create categories of TODOs from the admin panel, and users can create and complete their todos from the frontend. This exercise should allow us to cover most of the techniques used in customizing the platform.

This would be a good moment to review the Symfony Best Practices as it explains the directory structure and other recommendations we will be respecting.

• Docker
• Symfony
• Symfony Web Server