Split your Symfony views into multiple controllers with NumberNine CMS

William Arin — Fri, 13 Aug 2021 16:43:42 +0000

When building a simple page with Symfony, we usually end up having a controller and a view.

Oftentimes, things get complicated and one controller is not a viable solution anymore, therefore we need to split the view like this:

Symfony offers several ways to split your views into multiple controllers. NumberNine CMS offers two more. We'll see which cons and pros each method provides.

using Twig partials with include

{% include 'my_partial.html.twig' with {message: 'hello'} %}

using Twig partials with embed

{% embed 'my_partial.html.twig' %}
    {% block message %}hello{% endblock %}
{% endembed %}

using embedded controllers

{{ render(controller('MyController', {message: 'hello'})) }}

using Twig components

{{ component('my_component', {message: 'hello'}) }}

using NumberNine components

{{ N9_component('MyComponent', {message: 'hello'}) }}

using NumberNine shortcodes

{{ N9_shortcode('[my_shortcode message="hello"]') }}

Pros and cons of each technique

Twig includes and embeds are great and flexible but their data come from above, which makes the root controller bloated. Of course there are workarounds such as Twig extensions or global variables to access a service, but a view shouldn't retrieve data that the controller didn't send to it.

Embedded controllers are a good solution if they're used sporadically, as they make a new Request and will negatively impact performance.

Twig Components is a better approach than embedded controllers, although they have some limitations. Components are non shared services, which means a new instance is created at every call of {{ component('my_component') }}, erasing previously stored data. This means that if your component registers an event listener, it won't work as the instance is created on the fly.

NumberNine components

NumberNine Components solve the problem of Twig Component's separate instances by creating a new set of template parameters everytime the component is called, but the instance itself of the component stays the same.

A NumberNine Component is a shared service, hence event listeners registered will catch events as they should. Parameters injection is done through setters.

Here's a concrete example.

# templates/page/show.html.twig

{{ N9_component('MyComponent', {example: 'string variable'}) }}

// src/Component/MyComponent/MyComponent.php

final class MyComponent implements ComponentInterface
{
    private string $example;

    public function setExample(string $example): void
    {
        $this->example = $example;
    }

    public function getTemplateParameters(): array
    {
        return [
            'example' => $this->example,
        ];
    }
}

// src/Component/MyComponent/template.html.twig

<p>Displaying custom variable: {{ example }}.</p>

Moreover, just like every other view in NumberNine, component templates are overridable. The theme you use probably uses components, and you'll probably want to adapt the design.

Read more about components on the documentation page.

NumberNine shortcodes

While components are developer-oriented, shortcodes are a user-oriented way to inject templates in the view.

Also known as BBcodes, shortcodes and have been widely used in forums and CMS for years. They are represented by a string that the user can input in his editor.

They have a short syntax:

[my_shortcode message="hello"]

Or an extended syntax:

[my_shortcode]hello[/my_shortcode]

Extended syntax allows for nested shortcodes:

[my_shortcode]
    [my_nested_shortcode message="hello"]
[/my_shortcode]

NumberNine handles shortcodes as services. Each shortcode has its own class which acts like a controller.

As an example, we'll analyze this page header:

Now look at how it's rendered behind the scene:

This is not the result of a manual input in an editor, although it can. To know more about how it was rendered, see the last section of this article about the page builder.

Back to our view splitting. To put it simply, this header is composed of 9 controllers and 9 views, with no negative performance impact.

Let's take the my_account_link shortcode and see how it's built, as it's a very basic shortcode. Its purpose is to automatically link to the user-defined "My account" page:

/**
 * @Shortcode(name="my_account_link", label="My Account Link")
 */
final class MyAccountLinkShortcode extends AbstractShortcode
{
    public function configureParameters(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'loggedOutText' => 'Login / Register',
            'loggedInText' => 'My account',
        ]);
    }

    public function processParameters(array $parameters): array
    {
        return [
            'loggedOutText' => $parameters['loggedOutText'],
            'loggedInText' => $parameters['loggedInText'],
        ];
    }
}

While its template looks like this:

<a href="{{ N9_path(PAGE_FOR_MY_ACCOUNT) }}">
    {%- if is_granted('IS_AUTHENTICATED_REMEMBERED') -%}
        {{ loggedInText|trans }}
    {%- else -%}
        {{ loggedOutText|trans }}
    {%- endif -%}
</a>

Now it can be used either by the developer with {{ N9_shortcode('[my_account_link]') }}, or directly by the user in a text editor with [my_account_link].

That's all! Our views can be split in many ways and still keep a high performance. The main controller stays very light, and every partial controllers handle their own responsability. This makes the code highly reusable and easier to use for both developers and users.

Read more about shortcodes on the documentation page.

Shortcodes and the page builder

NumberNine's page builder relies on shortcodes to build the view. Each shortcode can be defined as an editable shortcode, which will appear in the page builder's list of available components to the user.

This will be the topic of an other article. Meanwhile, check out the documentation to see how to build a page builder component with a shortcode.

Symfony on steroids with NumberNine CMS

William Arin for NumberNine CMS ・ Aug 8 '21

#symfony #php #cms

Symfony on steroids with NumberNine CMS

William Arin — Sun, 08 Aug 2021 05:33:17 +0000

Web agencies and freelancers don't need to waste precious time on project setup and configuration anymore. With NumberNine's installer, you'll be able to start working on a Symfony app in seconds.

Copy/paste this installation one-liner in your terminal, given that you have Docker installed:

docker run --rm --pull=always -t -e HOST_PWD=$PWD \
    -v $PWD:/srv/app -v /var/run/docker.sock:/var/run/docker.sock \
    numberninecms/installer myproject

Boom! Done.

One minute later, even without any prior knowledge of Docker, here's what you get:

The latest Symfony version (symfony/web-skeleton)
The latest NumberNine version
The latest PHP, MySQL, Nginx, Redis, Maildev and blackfire versions running as Docker containers
A PHP Docker container with Cachetool, Composer 2, APCu, Xdebug 3, make, and zsh
A self-signed SSL certificate for myproject.localhost and HTTPS access
A ready-to-use website with all CMS features

Simplicity in mind

NumberNine is a CMS which focus on simplicity of use, both for the end-users and the developers. It automates most of the tedious steps of setting up a new Symfony project, while also easing the maintenance by the clients in charge of their content.

For instance:

Have you ever used MakerBundle to create user, registration form, etc.?
Have you ever created some CRUD controllers for your entities?
Have you ever installed VichUploaderBundle or implemented file upload?

If you answered yes to any of these questions, you'll most probably find benefits using NumberNine. All these are core features.

What's more? It's still a Symfony app, which means that you can develop things that won't interfere with the CMS, the Symfony way. NumberNine acts like an additional CMS layer, so you get the best of both worlds.

Some features

You'll find on this page an exhaustive list of features, but the most notable are:

Client-side image resizing with high quality downscaling algorithm
Granular user management with capabilities assigned to roles
WYSIWYG extensible page builder
Shortcodes
Relationships between entities
Menu creation
Easy Twig theming with inheritance (core -> theme -> app)

It's MIT license, totally free to use.

You can star it on Github if you like it.

numberninecms / cms

Core code of NumberNine CMS

The developer documentation is at https://numberninecms.com.

Bonus video trailer