Documentation

Creating controller

In Beacon, you can create controllers manually, or via console.

To create a new controller via console just do it like below.

console make:controller MyController

This will create the new controller file app/Controllers/MyController.php

You can also create a new controller in a specific namespace. To do so, just add the namespace in front of the controller name.

console make:controller MyNamespace/MyController

This will create the new controller file app/Controllers/MyNamespace/MyController.php

Dependency injection in controller methods

As you may have seen in the section 4.3 Routes with parameters, Beacon provides not only parameter injection, but also dependency injection.

Injecting a dependency into a controller method is as simple as described in the section 4.3 Routes with parameters:

use App\Controllers\Controller;
use App\Http\Request;

class MyController extends Controller
{
    public function myMethod(Request $request): Response
    {
        // Your code logic
    }
}

You can also inject multiple dependencies and route parameter at once. Important: Dependencies comes before route parameters.

use App\Controllers\Controller;
use App\Http\Request;

class MyController extends Controller
{
    public function myMethod(
        Request $request,
        ValidationService $validator,
        MailService $mailer,
        $param_first,
        $param_second
    ): Response {
        // Your code logic
    }
}

Validation

Beacon integrates Symfony Validator with DTO (Data Transfer Object) based validation.

The first step requires the creation of a DTO object:

console make:dto ExampleDto

This will create the file: app/DTO/ExampleDto.php

The next step is defining the validation assertions in the DTO as so-called "attributes", and adding the properties to the existing fromArray() and toArray() methods.

// File: app/DTO/ExampleDto.php

namespace App\DTO;

use Symfony\Component\Validator\Constraints as Assert;

class ExampleDto
{
    public function __construct(
        #[Assert\NotBlank]
        #[Assert\Email]
        public string $email,

        #[Assert\NotBlank]
        #[Assert\Length(min: 4, max: 100)]
        public string $name,
    ) { }

    public static function fromArray(array $data): self
    {
        return new self(
            email: trim($data['email']) ?? '',
            name: trim($data['name']) ?? '',
        );
    }

    public function toArray(): array
    {
        return [
            'email' => $this->email,
            'name' => $this->name,
        ];
    }
}

Now we can use this DTO to validate our form fields in our controller.

// File: app/Controllers/MyController.php

use App\Controllers\Controller;
use App\DTO\ExampleDto;
use App\Exceptions\ValidationException;
use App\Http\Request;
use App\Services\ValidationService;

class MyController extends Controller
{
    /**
     * @param Request $request
     * @param ValidationService $validator
     * @param MailService $mailer
     *
     * @throws ValidationException
     * @return Response
     */
    public function myMethod(
        Request $request,
        ValidationService $validator,
    ): Response {
        $dto = ExampleDto::fromArray($request->all());
        $validator->validate($dto);

        // Your additional code logic
    }
}

If the validation is successful, the code after

$validator->validate($dto);

will be executed. In case the validation fails, an ValidationException is thrown, which contains the errors incl. the related form field names, and is then handled by the Kernel.

To display the validation errors in the front-end (Twig template), please refer to the section 6.2 Handle validation errors.

To know more about the available validation constraints (attributes), please refer to the official Symfony Validation documentation.

Mailing

Beacon uses internally the PHPMailer to send emails. Also, you need an existing email account, which allows you to send emails via SMTP.
The configuration for PHPMailer have to be made in the .env file under "MAILER SETTINGS".

To send emails from within a controller, it requires only a few lines of code.

In this example, we use the previously created DTO and just inject the additional required MailService object in our method.

// File: app/Controllers/MyController.php

use App\Controllers\Controller;
use App\DTO\ExampleDto;
use App\Exceptions\ValidationException;
use App\Http\Request;
use App\Services\MailService;
use App\Services\ValidationService;

class MyController extends Controller
{
    /**
     * @param Request $request
     * @param ValidationService $validator
     * @param MailService $mailer
     *
     * @throws MailerException
     * @throws ValidationException
     * @return Response
     */
    public function myMethod(
        Request $request,
        ValidationService $validator,
        MailService $mailer,
    ): Response {
        $dto = ExampleDto::fromArray($request->all());
        $validator->validate($dto);

        // Sending a HTML message by using a Twig template
        $message = $this->view->render('mail/my_mail.twig', [
            'name' => $name,
        ]);

        $mailer->send(
            $dto->email,
            'Your Subject',
            $message,
            true,
        );

        // Alternative you can also send a PLAIN text message. To do so, you need to pass (bool) false as fourth
        // parameter to the send() method
        $mailer->send(
            $dto->email,
            'Your Subject',
            sprintf('Hallo .', $name),
            false,
        );
    }
}

Handle validation errors

The errors thrown by the ValidationService and handled in the Kernel, can be retrieved in Twig templates via the global errors variable. This variable is an array, which contains the form field name, for which the error is thrown, and also the related error messages.

The best way to display these errors is, to first check if the related field name exists in errors, and then walk through the field errors (which is also an array) to display them.

Example (show all errors for a specific field):

<form>
    <input
        type="email"
        name="email"
        class="input"
        placeholder="[email protected]"
    >
    <!-- Check if errors for the "email" field exists -->
    {% if errors.email is defined %}
        <div class="form-error mt-xs">
            <!-- Walk through the email field errors and display them -->
            {% for error in errors.email %}
                {{ error }}<br>
            {% endfor %}
        </div>
    {% endif %}
</form>

Example (show only the first error for a specific field):

<form>
    <input
        type="email"
        name="email"
        class="input"
        placeholder="[email protected]"
    >
    <!-- Check if errors for the "email" field exists -->
    {% if errors.email is defined %}
        <div class="form-error mt-xs">
            <!-- Show only the first error for this form field -->
            {{ errors.email|first }}
        </div>
    {% endif %}
</form>

The errors exists check, can also be used to add CSS class to the form field, to highlight the form field additionally.

Example:

<form>
    <input
        type="email"
        name="email"
        class="input{% if errors.email is defined %} field-error{% endif %}"
        placeholder="[email protected]"
    >
    {% if errors.email is defined %}
        <div class="form-error mt-xs">
            {% for error in errors.email %}
                {{ errors }}<br>
            {% endfor %}
        </div>
    {% endif %}
</form>

If a validation fails, Twig provides over another global variable old the old values of successfully validated form fields, which can be reused as "placeholder".

Example:

<form>
    <input
        type="email"
        name="email"
        class="input"
        placeholder="{{ old.email|default('[email protected]')|e }}"
    >
    {% if errors.email is defined %}
        <div class="form-error mt-xs">
            {{ errors.email }}
        </div>
    {% endif %}
</form>

Very important note:
The elements in the global errors variable are internally retrieved from a "flash" message, and therefore not persistent. This means as soon as you retrieve the element, it will be removed from the global errors variable. This is why you need to check the existence of the element first via is defined.

Helper functions

Beacon provides a few Twig helper functions, which can be used in Twig templates.

• route(): Get the route by name
  Example (without query arguments):

  
  <a href="{{ route('home') }}">Home</a>
  Result: <a href="/">Home</a>
  

  Example (with query arguments):

  
  <a href="{{ route('my-route', {'param_first' : 'first+value', 'param_second' : 'second value'}) }}">My route with params</a>
  Result: <a href="/my-path/first%2Bvalue/second+value">My route with params</a>
  

  Note: As you can see, the passed values are automatically URL encoded.

• old(): Retrieve all "old" flash data as array. Note: The related flash data will not be removed.
• errors(): Retrieve all "errors" flash data as array. Note: The related flash data will not be removed.
• flash(): Retrieves the flash data for "key". Note: The related flash data will be removed. Example usage:

  {{ flash('key-name', 'default value') }}

• guest(): Returns true if current user is not authenticated, otherwise false.
• currentRoute(): Returns the current route, example: /my-path
• isActiveRoute(): Returns true if the passed route name is the current active route, otherwise false. Example usage:

  
  {% if isActiveRoute('my-route') %}
      "my-route" is the current active route.
  {% else %}
      "my-route" is NOT the current active route
  {% endif %}
  

• csrf(): Returns an HTML hidden form element with an CSRF token as value. Example:

  
  {{ csrf() }}
  Result: <input type="hidden" name="_csrf" value="0d924a123d841aa1908a1599a87e5ab02a73703b2feb5a4229961d316f7a1c07">
  

• asset(): Returns the "assets" URL path. Example:

  
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
  Result: <link rel="stylesheet" href="/assets/css/styles.css">
  

• app_url(): Returns the full application URL incl. path. Example:

  
  <link rel="stylesheet" href="{{ app_url('css/styles.css') }}">
  Result: <link rel="stylesheet" href="https://example.org/assets/css/styles.css">
  

Global variables

Beacon provides a few global variables as listed below.

• old: Same functionality as the Twig helper function old()
• errors: Same functionality as the Twig helper function errors().
• _appName: Contains the value of the .env variable APP_NAME.
• _appSlogan: Contains the value of the .env variable APP_SLOGAN.
• _appVersion: Contains the value of the .env variable APP_VERSION.
• _appCopyright: Contains the value of the .env variable APP_COPYRIGHT.