Neos Flow Application with Fusion, AFX and DDEV

In this post, we’ll look at how to set up easily a Neos Flow application using the Docker tooling DDEV. In doing so, we also use the recommended view/templating technologies Fusion and AFX.

Install DDEV, start Docker Daemon

First we need to install DDEV, follow the instructions.

After that, make sure Docker is started on your end.

Create app directory and configure DDEV

Execute the following commands:

mkdir demo-app
cd demo-app
ddev config
# Set a project name or use the already proposed name (which would be in our case "demo-app")
# Docroot Location: set to "Web"
# Project type: set "php"

Set the Docroot directory to the value Web.

Configure also a current PHP version (for Flow 8.x PHP 8.0-8.1), a suitable database and some necessary Flow environment variables.

Open the DDEV config file .ddev/config.yaml and adjust it as follows:

...
php_version: "8.1"
webserver_type: apache-fpm
database:
  type: mariadb
  version: "10.4"
web_environment:
  - FLOW_CONTEXT=Development
  - FLOW_PATH_TEMPORARY_BASE=/tmp/demo-app
  - FLOW_REWRITEURLS=1
nodejs_version: "16"
...

You can find more DDEV configuration options in their documentation.

Create Flow application

Create now via the ddev and composer command (more about DDEV and Composer) a first folde structure for our Flow application based on the Flow base distribution repository.

ddev composer create neos/flow-base-distribution
# Confirm that any existing content in the project root will be removed

This command can take a few minutes, because initially the necessary DDEV container images have to be downloaded.

After that we get an empty framework to develop a Flow application later.

Start the application:

ddev start

With ddev describe you can get all the info about your application, e.g. what the url for the webserver is, etc.

For our application this is: https://demo-app.ddev.site.

When opening our application in the browser, an error message still appears. In order for our empty Flow application to work, we still need to provide a correct Settings.yaml.

Configure the Flow application

Create a Configuration/Settings.yaml file with the following content:

Neos:
  Imagine:
    driver: Imagick
  Flow:
    persistence:
      backendOptions:
        driver: 'pdo_mysql'  # use pdo_pgsql for PostgreSQL
        charset: 'utf8mb4'   # change to utf8 when using PostgreSQL
        dbname: db
        user: db
        password: db
        host: db

    # The following lines register the Flow default routes
    # For productive use you should move this setting to the main package of this
    # application and/or create custom routes.
    mvc:
      routes:
        'Neos.Flow': TRUE

    # The following is necessary to allow ddev to act as a proxy on your local machine
    http:
      trustedProxies:
        proxies: "*"

  # The following is optional, but will redirect all mails directly to ddev's MailHog
  SwiftMailer:
    transport:
      type: 'Swift_SmtpTransport'
      options:
        host: 'localhost'
        port: 1025
        encryption: ~

This configuration will be loaded directly on the next load and our Flow application should now work correctly: https://demo-app.ddev.site

Create Flow Application Package

We will now create our Flow application package:

ddev exec ./flow kickstart:package Demo.App

This command creates for us the basic skeleton for a Flow package. We can find this in the directory: DistributionPackages/Demo.App.

Also we can already call a first index page with: https://demo-app.ddev.site/demo.app.

Set up Fusion and AFX

To develop a Flow application with Fusion and AFX certain commands and configurations need to be done.

The next steps are based on the following Neos documentation:

• Flow Fusion template support
• Creating AFX-based Applications / Backend Modules

We will now create a first controller for our application:

ddev exec ./flow kickstart:actioncontroller --generate-fusion --generate-actions --generate-related Demo.App BlogArticle

The --generate-fusion option creates some example with Fusion templates.

We can now call our controller as follows: https://demo-app.ddev.site/demo.app/blogarticle.

But we still get an error:

"View class has to implement ViewInterface but "Neos\Fusion\View\FusionView" in action "index" of controller "Demo\App\Controller\BlogArticleController" does not."

For Fusion and AFX to work, the required dependencies and Flow configurations still need to be installed and configured.

Install the dependencies:

ddev composer require neos/fusion neos/fusion-afx neos/fusion-form

After that we clear the Flow cache and reload the package list:

ddev exec ./flow flow:cache:flush --force
ddev exec ./flow neos.flow:package:rescan

Now when the application is called with https://demo-app.ddev.site/demo.app/blogarticle, a correct page should be displayed.

If the following error message appears:

Call to a member function parse() on null

then the config under Configuration/Views.yaml must be entered correctly.

If necessary, create a file Configuration/Views.yaml with the following content:

- requestFilter: 'isPackage("Demo.App")'
  viewObjectName: 'Neos\Fusion\View\FusionView'
  options:
    fusionPathPatterns:
      - 'resource://Neos.Fusion/Private/Fusion'
      - 'resource://Demo.App/Private/Fusion'

Flow Application Ready

Our new Flow application with Fusion and AFX is now ready and can be developed further. Currently there is still an error message regarding database access when trying to access https://demo-app.ddev.site/demo.app/blogarticle. Here are still missing the appropriate database initializations, that would be a next step to tackle :).

Done - Shutdown DDEV and the application

With the following command you can shutdown your Flow application completely:

ddev poweroff
# Or if you only want to stop your container use: ddev stop

More DDEV CLI commands can be found here: Link