Roadmap of learning Spiral Framework

#Getting started

Spiral Framework is object-oriented framework that follows PHP Standard Recommendations. To be able to use it efficiently it is required to know basics of concepts like abstraction, usage of interfaces, design patterns like dependency injection, Model-view-controller architecture pattern and PHP features like attributes, that are widely use within the framework.

#Links and materials to read more:

1. PHP Standard Recommendations
2. Dependency injection
3. Refactoring.guru

#Benefits

Long living processes provide a lot of benefits, such as:

1. Performance Improvement: Traditional PHP applications boot up and shut down for each HTTP request. With long-living processes, the application only needs to boot once, significantly improving the performance by reducing the overhead associated with booting up and shutting down.
2. Memory Efficiency: Because processes are reused instead of being recreated for each request, memory usage can be more efficient, especially for applications with a large codebase or those that rely on significant amounts of data.
3. Persistence: Long-living processes allow for the persistence of certain elements (like database connections or cached data) across multiple requests, potentially leading to further improvements in speed and efficiency.
4. Concurrency: RoadRunner, for example, allows you to run PHP applications in a concurrent manner. This means you can handle multiple requests simultaneously without waiting for the previous one to finish, leading to better utilization of system resources and improved throughput.
5. Better Integration with Other Services: Long-living processes can be more easily integrated with services like message queues, websockets, etc., which require persistent connections.
6. Cost Efficiency: With less CPU and memory usage, the cost of hosting and server maintenance can be reduced.

#Links and materials to read more:

1. Long living processes

#Roadrunner

RoadRunner is a high-performance PHP application server designed for long-living processes. It keeps PHP apps in memory across requests, enhancing speed and efficiency. It manages memory usage, supports concurrent request handling, and integrates seamlessly with various services. This makes it ideal for complex tasks, mitigating traditional PHP limitations while offering scalability and robustness.

Roadrunner is part of Spiral Envirement and is highly integrated with Spiral Framework.

#Links and materials to read more:

1. Documentation
2. Github

#Memory Leaks

In the context of long-living processes, memory management becomes a crucial aspect. Since the application stays in memory for a long time, even a small memory leak might lead to process restart. RoadRunner, the application server used by Spiral, will monitor memory consumption and perform a soft reset, but it is best to avoid memory leaks in your application source code.

Memory leaks can occur when memory resources are allocated but not released after they are no longer needed. In the context of PHP, this can happen when large amounts of data are processed, or when resources like file handles or database connections are not properly closed.

Spiral Framework and all of its components are written with memory management in mind, but you still have to make sure that your domain code is not leaking. This includes being careful with global state, static properties, and closures, as they can inadvertently hold onto references to objects, preventing them from being garbage collected.

#Links and materials to read more:

1. Memory Leaks in Spiral Framework

#Stateless Approach in Spiral Framework

Spiral Framework adheres to a stateless approach, optimizing the separation of concerns between business logic and infrastructure tasks. In this model, the PHP codebase is focused on the efficient delivery of business logic, while the infrastructure tasks are handled by the Golang-based application server. The PHP application remains stateless across requests, making it more scalable and easier to maintain. This approach allows Spiral Framework to leverage the strengths of both PHP and Go.

#Links and materials to read more:

1. Framework overview
2. Design approach

#Singletons

Singletons are a design pattern that restricts a class to a single instance, providing a global point of access to it. This pattern is useful when exactly one object is needed to coordinate actions across the system.

In the Spiral Framework, Singletons are implemented via an interface or in a bootloader. One key point to keep in mind is that when a class is not explicitly defined as a Singleton, a new instance will be generated for each request.

This approach proves beneficial when there's a need to preserve data or maintain a connection between requests within the object properties.

#Links and materials to read more:

1. Singletons
2. Bootloaders

#Understanding long living processes

One of the key features of Spiral Framework is long living process supported by Roadrunner. This solution comes with set of benefits and cons that user must be aware of.

#Database configuration

Part of Spiral Environment is Cycle ORM, powerful library that provides abstraction layer for database. It has drivers for most popular databases such as MySQL, PostgreSQL and much more.

To configure connecting you should set up credentials in .env file.

#Links and materials to read more:

1. Cycle ORM Docs
2. Database and ORM

#Installation and configuration

Spiral Framework can be installed both natively or using Docker. Basic stack consists of PHP 8.1+, Roadrunner, database (supported by CycleORM). It can be enchanted by queue systems (e.g. RabbitMQ) or Temporal.

The installation process had been described in Spiral Framework documentation.

#Links and materials to read more:

1. Installation documentation

#Routing

Routing module allows to set under what URL the resource will be available. In Spiral Framework you can do that using attributes.

#[Route(route: '/', name: 'index', methods: 'GET')]

You can set HTTP method that will lead to given controller method and you can set additional parameters like id of the resource you want to process.

#Links and materials to read more:

1. Database and ORM

#Reading user data

Reading user data in Spiral Framework involves retrieving data sent by the user to the server via HTTP requests. This data can be sent through the URL (GET), form submissions (POST), or even through cookies and headers.

Here's a basic example of how you can read GET and POST data in Spiral Framework:

// Reading GET data
$queryParams = $request->getQueryParams();
$specificQueryParam = $request->getQueryParam('specificKey');

// Reading POST data
$parsedBody = $request->getParsedBody();
$specificPostParam = $request->getParsedBodyParam('specificKey');

In these examples, $request is an instance of Spiral\Http\Request\InputManager which is automatically injected into your controller methods.

#Links and materials to read more:

1. HTTP — Getting started
2. Request and Response in Spiral Framework
3. Routing in Spiral Framework

#First controller

Controller is part of MVC architecture pattern responsible for managing the flow of data and interactions between the model and the view components.

//todo, write more why to create controller, how to do it, what next.

#Links and materials to read more:

1. First controller

#Autowiring

Autowiring is a feature of the Spiral container that allows automatic resolution of class dependencies. This means that the container can automatically create and inject dependencies for a class without the need for explicit configuration.

The container supports advanced features like union types, variadic arguments, referenced parameters and default object values for the auto-wiring.

use Spiral\Core\Container\Autowire;
use Spiral\Session\Handler\FileHandler;

return [
    // ...
    'handler' => new Autowire(
        FileHandler::class,
        [
            'directory' => directory('runtime') . 'session',
            'lifetime' => (int)env('SESSION_LIFETIME', 86400),
        ]
    ),
];

#Links and materials to read more:

1. Container and DI

#Defining dependencies

The Spiral container allows you to configure it by creating bindings between interfaces or aliases to specific implementations. You can use Bootloaders to define these bindings. There are two ways to configure the container, either by using the Spiral\Core\BinderInterface or the Spiral\Core\Container.

To bind an interface to a concrete implementation, you can use the BinderInterface. To bind a singleton, you can use the BinderInterface as well. You can also bind with specific parameters by using the Autowire class.

Lastly, you can use closures to configure your class automatically by passing a closure to the bind or bindSingleton method.

$container->bind(SomeInterface::class, SomeClass::class); 

#Links and materials to read more:

1. Container and DI

#Dependency Injection

Dependency Injection is a design pattern that allows an object to receive other objects it depends on. Spiral includes a set of tools that makes it easier to manage dependencies and create objects in your code. One of the main tools is the container, which helps you handle class dependencies and automatically "injects" them into the class. This means that instead of creating objects and setting up dependencies manually, the container takes care of it for you.

The Spiral container also follows a set of PSR-11 Container standards, which ensures compatibility with other libraries. In your code, you can access the container by asking for the Psr\Container\ContainerInterface.

The Spiral container allows you to use both constructor and method injections for your classes. This means that you can have dependencies automatically injected into the class through the constructor, or through a specific method.

#Links and materials to read more:

1. Container and DI

#Debugging with Dumpers

Debugging is a crucial part of the development process. In Spiral Framework, you can use dumpers to inspect variables and objects during the execution of your code. This can be very useful for understanding the state of your application at any given point.

Spiral Framework provides its own built-in dumper. However, you can also use Symfony's VarDumper component, which provides several functions to dump variables in a more human-readable format.

Remember, the output of these dumpers will be sent to the output (browser, console, etc.) directly.

#Links and materials to read more:

1. Debugging in Spiral Framework
2. Symfony VarDumper

#Debugging with Xdebug

Xdebug is a powerful debugging and profiling tool for PHP. It provides a range of features like stack traces, breakpoints, and profiling information. Xdebug can be a valuable tool when debugging long-living processes in Spiral Framework.

However, keep in mind that using Xdebug with long-living processes can have a significant impact on performance. Therefore, it's recommended to use it in a development environment and disable it in production.

Xdebug can be installed as a PHP extension and configured in your php.ini file. Once installed, you can use it with various IDEs like PhpStorm, VS Code, etc., which provide built-in support for Xdebug.

Remember, debugging long-living processes requires a different approach compared to traditional web requests due to their persistent nature.

#Links and materials to read more:

1. Xdebug
2. Debugging in Spiral Framework

#Debugging

Debugging code in long-living processes can be challenging due to the nature of these processes. They are designed to stay active for a long time, and therefore, traditional debugging methods might not always work as expected.

#Links and materials to read more:

1. Debugging

#05.1 Configuration

Configuring Cycle ORM involves setting up your database connections and mapping your entities to the database schema. This is usually done in the .env file for your application.

// .env file
DATABASE_URL=mysql://user:password@localhost:3306/database

#Links and materials to read more:

1. Cycle ORM Docs
2. Database and ORM

#First entity

Entity in Spiral Framework is an object that represents data and its relations to different entities. Through the power of CycleORM it allows to map object structure and configuration into database table.

#Links and materials to read more:

1. Cycle ORM Docs
2. Database and ORM

#05.3 Migrations

Migrations in Spiral Framework are a way of applying version control to your database. They allow you to manage your database schema and data changes over time.

#Links and materials to read more:

1. Cycle ORM Docs
2. Database and ORM

#05.4 Relations

Relations in Spiral Framework are managed through Cycle ORM. It allows you to define the relationships between your entities, such as one-to-one, one-to-many, and many-to-many.

namespace App\Entity;

use Cycle\Annotated\Annotation\Entity;
use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Relation\BelongsTo;

/**
 * @Entity()
 */
class Post
{
    // ...

    /**
     * @BelongsTo(target="User", nullable=false)
     * @var User
     */
    public $user;
}

#Links and materials to read more:

1. Cycle ORM Docs
2. Database and ORM

#05.5 Schema debugging

Schema debugging in Spiral Framework involves inspecting your database schema to ensure it matches your entities' configurations. This can be done using various tools and techniques.

$schema = $orm->getSchema();
$table = $schema->define('users');

var_dump($table->getColumns());

#Links and materials to read more:

1. Cycle ORM Docs
2. Database and ORM

#Database and ORM

The Spiral Framework provides a powerful and flexible Object-Relational Mapping (ORM) tool for PHP that allows developers to interact with databases in an object-oriented way. It supports a variety of popular relational databases such as MySQL, MariaDB, PostgresSQL, SQLServer, and SQLite.

Cycle ORM, the ORM tool provided by Spiral, offers a range of features that make it easy to work with data. These include flexible configuration options, a powerful query builder, and support for dynamic mapping of schemas. It also provides functionalities for transactions, entity validation, and entity behaviors.

#Links and materials to read more:

1. Cycle ORM Docs

#06.1 Saving entities

Saving entities in Spiral Framework involves creating an instance of your entity, setting its properties, and then using the persist and run methods of the Transaction class to save it to the database. This process is also known as persisting an entity.

$user = new User();
$user->username = 'test';
$user->password = 'test';

$transaction = new Transaction($orm);
$transaction->persist($user);
$transaction->run();

In the following example, we create a new User entity, set its username and password properties, and then persist it to the database using a Transaction.

#Links and materials to read more:

1. Cycle ORM Docs
2. Database and ORM

#06.2 Repositories and queries

Repositories in Spiral Framework provide a way to encapsulate database queries related to a specific entity. You can use the select method of the Repository class to create queries. This method returns a Select object, which you can use to add conditions to your query and fetch the results.

$users = $orm->getRepository(User::class)->select()->where('username', 'test')->fetchAll();

In the following example, we use the select method to create a query that fetches all User entities where the username is 'test'.

#Links and materials to read more:

1. Cycle ORM Docs
2. Database and ORM

#06.3 Queries debugging

Debugging queries in Spiral Framework can be done using the __toString method of the Select class, which will return the SQL query as a string. This can be useful for understanding what SQL query is being executed when you run your query.

$query = $orm->getRepository(User::class)->select()->where('username', 'test');
echo $query->__toString();

In the following example, we create a query and then print the SQL query to the console.

#Links and materials to read more:

1. Cycle ORM Docs
2. Database and ORM

#Reading and Storing Data

Working with data is a fundamental part of any application. In Spiral Framework, this involves interacting with the database and ORM (Object-Relational Mapping) to read and store data.

The Spiral Framework uses Cycle ORM, a PHP DataMapper, and ORM that simplifies the interaction between your PHP application and the database. It provides a simple, flexible, and powerful API to perform various database operations.

The process of reading and storing data in Spiral Framework typically involves:

• Entities: These are the PHP objects that represent the data you're working with. Each entity corresponds to a table in the database, and each instance of an entity represents a row in that table.

• Repositories: These are classes that encapsulate the database queries related to a specific entity. They provide methods to fetch and save entities, making it easier to perform common database operations.

• Transactions: These are used to ensure that multiple database operations are performed atomically. This means that if one operation fails, all the operations in the transaction are rolled back, maintaining the integrity of your data.

• Queries: These are used to fetch data from the database. Cycle ORM provides a powerful query builder that allows you to create complex queries in an easy-to-understand way.

In the following sections, we'll dive deeper into each of these topics, providing examples and links to further resources for you to explore.

#Links and materials to read more:

1. Cycle ORM Docs
2. Database and ORM

#Which template engine to choose

Spiral Framework supports multiple templating engines, including PHP itself, Twig, and others. The choice of templating engine depends on your specific needs and preferences. PHP itself can be a good choice for simple views, while Twig provides a more powerful and flexible syntax for complex views.

#Links and materials to read more:

1. Spiral Views

#How to render first page

Rendering a page in Spiral Framework involves creating a view, passing data to it, and then returning it from your controller. The render method of the ViewInterface is used to render the view.

#Links and materials to read more:

1. Spiral Views

#Using data in the templates

Data can be passed to the templates using the with method of the ViewInterface. This method accepts an array of data that will be available in the template.

return $views->get('home')
   ->with(['name' => 'John Doe']);

#Links and materials to read more:

1. Spiral Views

#Layouts and blocks

Layouts and blocks provide a way to define a common structure for your views. A layout is a template that defines the overall structure of the page, while blocks are sections of the layout that can be overridden by individual views.

<!-- layout.php -->
<html>
<body>
    <div class="content">
        <?= $this->block('content') ?>
    </div>
</body>
</html>

#Links and materials to read more:

1. Spiral Views

#07.0 Templating

Templating in Spiral Framework is handled by the Spiral Views library. This library provides a simple and flexible way to manage and render your views. It supports multiple templating engines, including PHP itself, Twig, and others.

#Links and materials to read more:

1. Spiral Views

#Creating forms in template

Forms in Spiral Framework are mostly regular HTML forms that have the AJAX submission functionality on top. The form can be created using standard HTML form elements. Once the form is submitted, you can access the submitted data in your Spiral controller using the request object.

Here is an example of how to create a form using HTML:

<form action="/submit" method="POST">
    <input type="text" id="name" name="name"><br>
    <input type="password" id="password" name="password"><br>
    <input type="submit" value="Submit">
</form>

And here is how you can access the submitted data in your Spiral controller:

use Spiral\Http\Request\InputManager;

class UserController
{
    public function submit(InputManager $input)
    {
        $name = $input->data('name');
        $password = $input->data('password');

        // Process the submitted data...
    }
}

Links and materials to read more:

1. Spiral Validation

#Validating user input

The validation component of Spiral allows you to validate data that is submitted by a user or received from an external source. The component does not contain any validator implementation out of the box. Instead, it provides a set of interfaces and abstract classes that define the expected behavior of a validator.

There are three validator bridges available for use with Spiral validation component:

• Spiral Validator - This is the default validator bridge. It is a simple, lightweight validator that can handle basic validation tasks.
• Symfony Validator - This validator bridge provides integration with the Symfony Validator component, which is a more powerful and feature-rich validation library.
• Laravel Validator - This validator bridge provides integration with the Laravel Validator, which is a validation component used in the Laravel framework.

Here is an example of how to validate data using the default validator:

use Spiral\Http\Request\InputManager;
use Spiral\Validation\ValidatorInterface;

class UserController
{
    public function create(InputManager $input, ValidatorInterface $validator)
    {
        $validator = $validator->validate([
            'username' => $input->post('username'),
            'email' => $input->post('email'),
        ], [
            'username' => 'required',
            'email' => 'required|email',
        ]);
        
        if (!$validator->isValid()) {
            $errors = $validator->getErrors();
            // ...
        }

        // Store the user in the database...
    }
}

Links and materials to read more:

1. Spiral Validation

#Request validation

Request validation is an important aspect of building secure and robust web applications. Spiral Framework provides a powerful validation library that allows you to validate incoming HTTP requests in a simple and flexible way.

#Links and materials to read more:

1. Spiral Validation

#CLI Commands

Command Line Interface (CLI) commands are a powerful tool in Spiral Framework. They empower you to automate tasks, perform maintenance, and much more. You can add new console commands to your application or register plugin commands using bootloaders. The component is configured by default to automatically discover commands located in the app/src directory.

To create a new command, you can either extend Symfony\Component\Console\Command\Command or Spiral\Console\Command. Extending the Spiral\Console\Command class provides some additional syntax sugar and convenience methods that can make it easier to build your command.

Spiral offers the ability to define console commands using PHP attributes. This allows for a more intuitive and streamlined approach to defining commands with clear separation of concerns.

Here's an example of defining a console command using attributes:

namespace App\Api\Cli\Command;

use Spiral\Console\Attribute\Argument;
use Spiral\Console\Attribute\AsCommand;
use Spiral\Console\Attribute\Option;
use Spiral\Console\Command;
use Symfony\Component\Console\Input\InputOption;

#[AsCommand(
    name: 'app:create:user', 
    description: 'Creates a user with the given data'
)]
final class CreateUser extends Command
{
    #[Argument]
    private string $email;

    #[Argument(description: 'User password')]
    private string $password;

    #[Argument(name: 'username', description: 'The user name')]
    private string $userName;

    #[Option(shortcut: 'a', name: 'admin', description: 'Set the user as admin')]
    private bool $isAdmin = false;

    public function __invoke(): int
    {
        $user = new User(
            email: $this->email,
            password: $this->password,
        );
        
        $user->setIsAdmin($this->isAdmin);
        
        // Save user to database...

        return self::SUCCESS;
    }
}

Links and materials to read more:

1. Console Application - User Commands

#Scaffolding and prototyping

Spiral Framework provides powerful tools for scaffolding and prototyping, which can significantly speed up the development process. These tools allow developers to quickly generate application code for various classes using a set of console commands.

#Scaffolding

Spiral provides a scaffolder component that enables developers to quickly and easily generate application code for various classes, using a set of console commands. These include application bootloaders, console commands, application configs, HTTP controllers, middleware, request filters, and queue job handlers.

The scaffolder component can be customized to fit your needs by replacing declaration generators and their options using the scaffolder configuration file. You can customize the class namespace, postfix, and declaration type for each available class declaration type.

// Example of using the PrototypeTrait in a class
namespace App\Endpoint\Web;

use Spiral\Prototype\Traits\PrototypeTrait;

class HomeController
{
    use PrototypeTrait;

    public function index()
    {
        return $this->views->render('profile', [
            'user' => $this->users->findByName('Antony')
        ]);
    }
}

#Prototyping

Spiral comes with a development extension that speeds up the development of application services, controllers, middleware, and other classes via AST modification. This extension includes IDE-friendly tooltips for most common framework components and Cycle Repositories.

To use the prototyping abilities of the framework, add Spiral\Prototype\Traits\PrototypeTrait to any of your classes. Once it's added, your IDE will immediately suggest available classes and Cycle Repositories to you.

// Example of customizing the scaffolder configuration
use Spiral\Scaffolder\Declaration;

return [
    'declarations' => [
        Declaration\MiddlewareDeclaration::TYPE => [
            'class' => Declaration\MiddlewareDeclaration::class,
        ],
        Declaration\CommandDeclaration::TYPE => [
            'namespace' => 'Endpoint\Console',
        ],
        Declaration\JobHandlerDeclaration::TYPE => [
            'namespace' => 'Endpoint\Queue',
            'postfix' => 'Job',
        ],
    ],
];

#Links and materials to read more:

1. Prototyping
2. Scaffolding

#Cookies and sessions

Spiral Framework provides robust support for managing cookies and sessions, which are essential for maintaining state in web applications.

#Cookies

Cookies in Spiral are managed by the CookieManager middleware, which provides a CookieQueue class for managing cookies within a specific scope. This middleware is automatically mounted in the HTTP config and runs on every request, allowing you to access the cookie queue inside your controllers using either dependency injection or the shortcut cookies.

Note that CookieQueue is not the same as request cookies. To access request cookies, you can use $this->input->cookies.

// Setting a cookie
public function indexAction(CookieQueue $cookies)
{
   $cookies->set('hello', 'world');
   
   $this->cookies->set('abc', 'value');
}

#Sessions

Spiral provides a SessionInterface for managing user sessions. You can access the user session using this interface. The session will be automatically started on first data access and committed when the request leaves SessionMiddleware.

// Accessing the session
use Spiral\Session\SessionInterface;

public function index(SessionInterface $session): void
{
    $session->resume();
    dump($session->getID());
}

You can also create a named section of the session using the getSection method of the session object.

// Creating a named section of the session
public function index(SessionInterface $session): void
{
    $cart = $session->getSection('cart');

    $cart->set('items', ['my-items']);

    dump($cart->getAll());
}

#Links and materials to read more:

1. Sessions
2. Cookies

#Environment variables

Environment variables are a great way to separate the configuration of your application from the code itself. This makes it easy to store sensitive information like database credentials, API keys, and other configs that you don't want to hardcode into your application.

Spiral integrates with Dotenv through the Spiral\DotEnv\Bootloader\DotenvBootloader class. This bootloader is responsible for loading the environment variables from the .env file and making them available to the application. It is a common practice to include a .env.sample file in a new project which can be used as a guide for setting up the environment variables.

You can access environment variables using Spiral\Boot\EnvironmentInterface or via a short function env().

// Accessing environment variables using Spiral\Boot\EnvironmentInterface
use Spiral\Boot\EnvironmentInterface;

final class GithubClient
{
    public function __construct(
        private readonly EnvironmentInterface $env
    ) {}

    public function getAccessToken(): ?string
    {
        return $this->env->get('GITHUB_ACCESS_TOKEN');
    }
}

Remember that the values in .env will be pre-processed, the following changes will take place:

// Accessing environment variables via a short function env()
return [
    'access_token' => env('GITHUB_ACCESS_TOKEN'),
    // ...
];

• true or (true) will be converted to boolean true
• false or (false) will be converted to boolean false
• null or (null) will be converted to null
• empty will be converted to an empty string ''

The quotes around strings will be stripped automatically.

#Links and materials to read more:

1. Environment Variables

#Input validation

Input validation is a crucial part of any API. It ensures that the data your API receives is in the correct format and meets your application's requirements. Spiral Framework provides a powerful validation library that allows you to validate incoming HTTP requests in a simple and flexible way.

// Input validation
use Spiral\Validation\ValidationInterface;

public function create(ValidationInterface $validation)
{
    $validation->rule('name', 'notEmpty')->rule('email', 'email');

    if (!$validation->isValid()) {
        return $validation->getErrors();
    }

    // Continue processing...
}

You can define validation rules for your API endpoints and apply them to the incoming request data. If the validation fails, Spiral will automatically generate a response with the validation errors.

#Links and materials to read more:

1. Request Validation

#Returning data

When creating an API, it's important to structure your responses in a way that's easy for clients to understand and use. Spiral Framework provides several ways to return data from your API endpoints.

You can return data directly from your controller methods, and Spiral will automatically convert it to a JSON response. If you need more control over the response, you can use the ResponseFactory service to create a response with custom headers, status code, and body.

// Returning data
use Spiral\Http\Response\ResponseFactory;

public function index(ResponseFactory $response)
{
    $data = ['message' => 'Hello, world!'];

    return $response->json($data);
}

#Links and materials to read more:

1. Responses

#Creating API

Creating an API with Spiral Framework involves handling input validation and returning data in a structured format. Spiral provides tools and features that make these tasks easier and more efficient.

#Links and materials to read more:

1. Request Validation
2. Responses

#Middlewares

Middlewares in Spiral Framework are based on the PSR-15 standard, which defines a common interface for processing HTTP server requests using middleware. Middleware is responsible for handling functionality that is related to the request and response, such as authentication, caching, or logging. It can modify the request and response before they are passed on to the router, but it cannot make decisions about which routes should be handled by the application.

// Creating a middleware
namespace App\Endpoint\Web\Middleware;

use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Http\Message\ResponseInterface;

class MyMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request, 
        RequestHandlerInterface $handler
    ): ResponseInterface {
        return $handler->handle($request)->withAddedHeader('My-Header', 'my-value');
    }
}

Spiral provides several ways to set middleware, allowing developers to choose the approach that best fits their needs. You can activate a global middleware that applies to all routes and requests, or you can configure middleware that's grouped and will only be applied to routes within the corresponding group. You can also apply middleware to a specific route.

// Adding a middleware to a route
namespace App\Application\Bootloader;

use Spiral\Bootloader\Http\RoutesBootloader as BaseRoutesBootloader;
use Spiral\Router\Loader\Configurator\RoutingConfigurator;
use App\Endpoint\Web\Middleware\MyMiddleware;

final class RoutesBootloader extends BaseRoutesBootloader
{
    protected function defineRoutes(RoutingConfigurator $routes): void
    {
        $routes->add(name: 'news.show', pattern: '/news/<id:int>')
            ->middleware(['middleware:web', MyMiddleware::class]);
    }
}

Spiral Framework allows developers to combine middleware with the IoC scope to create a request-specific application context. This allows developers to set up a context for the current request, which can be accessed by other parts of the application. This can be useful for tasks such as logging or data access, where the context of the request is important.

#Links and materials to read more:

1. Middlewares

#Making registration form

Creating a registration form in Spiral Framework involves creating a form in your application and handling the form submission in a controller. The form should include fields for the user's information, such as their name, email, and password. When the form is submitted, the controller should validate the input, create a new user in the database, and log the user in.

#Links and materials to read more:

1. Quick Start Guide

#Making registration form

Creating a registration form in Spiral Framework involves creating a form in your application and handling the form submission in a controller. The form should include fields for the user's information, such as their name, email, and password. When the form is submitted, the controller should validate the input, create a new user in the database, and log the user in.

#Links and materials to read more:

1. Quick Start Guide

#Creating user through CLI

Creating a user through the command-line interface (CLI) in Spiral Framework involves creating a console command that accepts user data as arguments and uses this data to create a new user in the database.

#Links and materials to read more:

1. Console Application Guide

#Storing users session

Storing user sessions in Spiral Framework is managed through the SessionInterface. This interface provides methods to control the session lifecycle, including resuming, committing, aborting, getting the session ID, destroying, and regenerating the ID of a session.

Sessions in Spiral are stored in the file system in the runtime/session directory by default. If your application will be load balanced across multiple web servers, you should choose a centralized store that all servers can access, such as Redis.

#Links and materials to read more:

1. Basics - Session Guide

#Authentication

Authentication in Spiral Framework is managed through a set of components that authorize users via temporary or permanent tokens from different sources. It safely manages the user context and does not enforce any specific User entity interface, allowing for flexibility in application design. The authentication extension creates an IoC scope for Spiral\Auth\AuthContextInterface which points to the currently authorized actor (User, API Client). The actor is fetched from Spiral\Auth\ActorProviderInterface using Spiral\Auth\TokenInterface. The token is managed by Spiral\Auth\TokenStorageInterface and always includes the payload (for example ["userID" => $id], LDAP creds, etc.). The token payload is used to find the current application user via Spiral\Auth\ActorProviderInterface.

#Links and materials to read more:

1. Authentication Documentation

#How to throw and handle 403, 404 and 500 pages

In Spiral Framework, you can throw HTTP level error pages from your controllers and middleware using specific exceptions. Here are the exceptions for 403, 404, and 500 HTTP status codes:

• 403 Forbidden: Spiral\Http\Exception\ClientException\ForbiddenException
• 404 Not Found: Spiral\Http\Exception\ClientException\NotFoundException
• 500 Internal Server Error: Spiral\Http\Exception\ClientException\ServerErrorException

When these exceptions are thrown, the default error handling middleware intercepts them and renders an error page. You can customize the error page renderer by implementing the Spiral\Http\ErrorHandler\RendererInterface.

#Links and materials to read more:

1. Error Handling Documentation

#Error Handling

Error handling in Spiral Framework is managed through a set of components that intercept and log critical errors and user-level exceptions. The framework includes a default error handling middleware Spiral\Http\Middleware\ErrorHandlerMiddleware which is used to intercept and log these errors. This middleware can be enabled in the global middleware list.

The framework also provides several exceptions that can be thrown from your controllers and middleware to cause HTTP level error pages. For example, you can trigger a 404 Not Found using NotFoundException.

#Links and materials to read more:

1. Error Handling Documentation

#Logging

Logging is an essential part of any application. It helps in debugging issues and keeping track of application activities. Spiral Framework uses Monolog, a popular logging library for PHP. Monolog allows for a variety of powerful log handling and storage options.

In Spiral, you can configure logging channels that handle different types of log messages. Each channel can have its own set of handlers and processors. Handlers are responsible for writing the log entries to their respective targets, such as files, databases, or external services. Processors modify the log entries before they are written, for example, by adding additional information.

To use logging in your Spiral application, you can obtain an instance of the Psr\Log\LoggerInterface from the container. This logger is configured with the settings defined in your application's configuration.

// Obtaining an instance of the logger
$logger = $container->get(\Psr\Log\LoggerInterface::class);

You can log messages at different levels, including debug, info, notice, warning, error, critical, alert, and emergency. Each level represents a different severity of the log message.

// Logging a message
$logger->info('This is an informational message');
$logger->error('An error occurred');

Links and materials to read more:

1. Monolog Documentation
2. PSR-3 Logger Interface

#Why to use cache

Caching is a technique used to store frequently accessed data in a faster storage medium, such as memory, instead of a slower source like a database. This can significantly improve the performance of an application by reducing the need to recalculate or fetch the data from the slower source every time it is needed.

By implementing a caching layer, the application can quickly retrieve the data from the cache instead of recalculating it or fetching it from the slower source. This can improve the overall response time of the application and reduce the load on the slower source.

In Spiral, RoadRunner is used as the underlying technology for the cache data layer, which provides several benefits. RoadRunner is written in Go, a language known for its performance and efficiency, and is designed to handle high-performance and concurrent workloads.

#Links and materials to read more:

1. Caching Documentation

#PSR-16

PSR-16, also known as the Common Interface for Caching Libraries, is a standard that describes a simple yet extensible interface for a cache item and a cache driver. It is designed to improve the interoperability of caching libraries, making it easier for libraries to drop their own caching implementations and easily rely on the one given to them by the framework, or another dedicated cache library.

The Spiral Framework's spiral/cache component is compliant with the PSR-16 standard. This means that it supports all serializable PHP data types, including strings, integers, floats, booleans, null, arrays, and objects that support lossless serialization and deserialization.

Here is an example of how to use the set method, which persists data in the cache, uniquely referenced by a key with an optional expiration TTL time:

$data = $this->cache->get('key');

And here is how to store an item in the cache:

$this->cache->set(
    key: 'key', 
    value: ['some' => 'data']
);

#Links and materials to read more:

1. PSR-16: Common Interface for Caching Libraries
2. Caching Documentation

#Caching

Caching is a technique that can significantly improve the performance of an application by storing frequently accessed data in a faster storage medium, such as memory. This reduces the need to recalculate or fetch the data from a slower source, such as a database. By implementing a caching layer, the application can quickly retrieve the data from the cache instead of recalculating it or fetching it from the slower source, which can improve the overall response time and reduce the load on the slower source.

The Spiral Framework's spiral/cache component allows for efficient storage and retrieval of data. It is compliant with the PSR-16 standard. In Spiral, RoadRunner is used as the underlying technology for the cache data layer, which provides several benefits. RoadRunner is written in Go, a language known for its performance and efficiency, and is designed to handle high-performance and concurrent workloads. Additionally, the RoadRunner Key-Value plugin provides a wide range of storage options, including popular solutions such as Redis Server or Memcached, as well as options that do not require a separate server, such as BoltDB. By using RoadRunner, the framework can take advantage of its performance and efficiency to handle caching more efficiently, which can ultimately improve the overall performance of the application.

#Links and materials to read more:

1. Caching Documentation

#Which dispatcher to choose

When choosing an event dispatcher, it's important to consider the needs of your application. Spiral Framework provides a default event dispatcher that you can use, but you can also create your own if you need more control over the dispatching process. The default dispatcher calls listeners synchronously in the order they are returned from a ListenerProvider. It returns the same Event object it was passed after it is done invoking listeners and does not return to the Emitter until all listeners have executed.

#Links and materials to read more:

1. Spiral Framework Events Documentation

#PSR-14

PSR-14 is a PHP standard that defines interfaces for dispatching events. It allows libraries and components to be reused more freely between various applications and frameworks. Spiral Framework's event system is compatible with PSR-14, which means you can use any PSR-14 compatible event dispatcher with Spiral Framework.

#Links and materials to read more:

1. PSR-14: Event Dispatcher

#Events

Events in Spiral Framework are a way for different parts of your application to communicate with each other. This is done by dispatching events and listening to them. The framework provides tools to make this process easy and efficient. It also provides an easy way to integrate PSR-14 compatible EventDispatcher.

An event is a message produced by an Emitter. It may be any arbitrary PHP object. A Listener is any PHP callable that expects to be passed an Event. Zero or more Listeners may be passed the same Event. A Listener MAY enqueue some other asynchronous behavior if it so chooses.

Here is an example of how to create an event:

// Event creation
namespace App\Event;

use App\Database\User;

final class UserWasCreated
{
    public function __construct(
        public readonly User $user
    ) {
    }
}

And here is how to dispatch an event:

// Dispatching an event
namespace App\Service;

use Psr\EventDispatcher\EventDispatcherInterface;
use App\Event\UserWasCreated;

final class UserService 
{
    public function __construct(
        private readonly EventDispatcherInterface $dispatcher
    ) {
    }

    public function create(string $username): User
    {
        $user = new User(username: $username);
        // ...
        $this->dispatcher->dispatch(new UserWasCreated($user));
        
        return $user;
    }
}

Finally, this is how you can create a listener:

// Listener creation
namespace App\Listener;

use App\Event\UserWasCreated;
use Spiral\Events\Attribute\Listener;

#[Listener]
class UserWasCreatedListener
{
    public function __invoke(UserWasCreated $event): void
    {
        // ...
    }
}

#Links and materials to read more:

1. Spiral Framework Events Documentation

#Creating task and dispatching it

To create a task in Spiral, you need to create a job handler. Job handlers are classes responsible for performing specific tasks or actions within the system. To create a job handler, you need to implement the Spiral\Jobs\HandlerInterface interface. Spiral also provides a convenient abstract class called Spiral\Queue\JobHandler that you can extend to simplify the implementation of your job handlers.

Once you have a job handler, you can dispatch your job via Spiral\Queue\QueueInterface or via the prototype property queue. When you request the Spiral\Queue\QueueInterface from the container, you will receive an instance of the default queue connection. The method push of QueueInterface accepts a job name, the payload, and additional options.

Here is an example of how to create a job handler and dispatch a job:

namespace App\Endpoint\Job;

use Spiral\Queue\JobHandler;

final class SampleJob extends JobHandler
{
    public function invoke(string $id, array $payload, array $headers): void
    {
        // Do something with service
    }
}

use App\Endpoint\Job\SampleJob;
use Spiral\Queue\QueueInterface;

public function createJob(QueueInterface $queue): void
{
    $queue->push(SampleJob::class, ['value' => 123]);
}

#Links and materials to read more:

1. Spiral Queue and Jobs
2. Spiral Queue Configuration

#Brokers

Queue aliasing is a feature that allows your application and modules to access the queue system in a variety of ways, using separate connections that are related to a single physical queue. To obtain a queue instance by its name or alias, you can use the getConnection method of the Spiral\Queue\QueueConnectionProviderInterface.

If the available queue driver does not meet your specific needs, you can create your own custom driver by implementing the Spiral\Queue\QueueInterface interface.

Here is an example of how to use queue aliasing and create a custom queue driver:

return [
    'aliases' => [
        'mailQueue' => 'roadrunner',
        'ratingQueue' => 'sync',
    ],
];

use Spiral\Queue\QueueConnectionProviderInterface;

$container->bind(MyService::class, function(QueueConnectionProviderInterface $provider) {
    return new MyService($provider->getConnection('mailQueue'));
})

final class MyService
{
    public function __construct(
        private readonly QueueInterface $queue
    ) {
    }
}

'connections' => [
    'mail' => [
        'driver' => \App\Infrastructure\Queue\RedisQueue::class,
        'server' => 'redis://localhost:6379',
        'queueName' => 'mail',
    ],
],

'driverAliases' => [
    'redis' => \App\Infrastructure\Queue\RedisQueue::class,
    // ...
],

#Links and materials to read more:

1. Spiral Queue and Jobs
2. Spiral Queue Configuration

#Running tasks in background

Spiral provides support for background PHP processing and a queue system. This feature is available out of the box and allows you to work with a variety of message brokers. To use this feature, you need to add Spiral\Queue\Bootloader\QueueBootloader to your application kernel.

The default queue configuration can be found in the app/config/queue.php file. This configuration file includes a set of options for each queue driver as well as aliases, which allow you to specify a default queue driver for your application to use.

Here is an example of how to set up the queue configuration:

protected const LOAD = [
    // ...
    \Spiral\Queue\Bootloader\QueueBootloader::class,
    // ...
];

return [
    /** Default queue connection name */
    'default' => env('QUEUE_CONNECTION', 'sync'),

    /** Aliases for queue connections, if you want to use domain specific queues */
    'aliases' => [
        // 'mailQueue' => 'null',
        // 'ratingQueue' => 'sync',
    ],
    
    'connections' => [
        'sync' => [
            // Job will be handled immediately without queueing
            'driver' => 'sync',
        ],
        'null' => [
            // Do nothing
            'driver' => 'null',
        ],
    ],
    
    'registry' => [
        'handlers' => [
            'sample::job' => App\Jobs\SampleJob::class
        ],
        'serializers' => [
            ObjectJob::class => 'json',
        ]
    ],
    
    'driverAliases' => [
        'sync' => \Spiral\Queue\Driver\SyncDriver::class,
        'null' => \Spiral\Queue\Driver\NullDriver::class,
    ],
];

#Links and materials to read more:

1. Spiral Queue and Jobs
2. Spiral Queue Configuration

#Roles

In Spiral, roles are used to manage user permissions. Each user is associated with one or more roles, and each role is associated with one or more permissions. To use the RBAC component, you must register available roles and create an association between the role and the permission. You can use the Spiral\Security\PermissionsInterface for this purpose. Once the roles are created, you can associate them with permissions using the associate method.

Here is an example of how to create a role and associate it with a permission:

namespace App\Bootloader;

use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Security\PermissionsInterface;

class SecurityBootloader extends Bootloader
{
    public function boot(PermissionsInterface $rbac): void
    {
        $rbac->addRole('user');
        $rbac->associate('user', 'home.read');
    }
}

#Links and materials to read more:

1. Spiral Security - Role Based Access Control

#Policies

In addition to roles, Spiral also provides a way to manage permissions using policies. Policies are rules that determine what actions a user can perform on a specific resource. They provide an additional layer of rules to control the privilege/permission context.

You can create complex role-permission associations using policies. For example, you can grant access to all of the namespace permissions, excluding specific ones. To forbid role access, you can use Spiral\Security\Rule\ForbidRule.

Here is an example of how to create a policy:

namespace App\Bootloader;

use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Security\PermissionsInterface;
use Spiral\Security\Rule\ForbidRule;

class SecurityBootloader extends Bootloader
{
    public function boot(PermissionsInterface $rbac): void
    {
        $rbac->addRole('guest');
        $rbac->associate('guest', 'home.*');
        $rbac->associate('guest', 'home.read', ForbidRule::class);
    }
}

#Links and materials to read more:

1. Spiral Security - Role Based Access Control

#Permissions

The Spiral Framework includes the component spiral/security, which provides the ability to authorize user/actor access to specific resources or actions based on the list of associated privileges. The components implement "Flat RBAC" patterns described in NIST RBAC research. The implementation includes multiple additions such as an additional layer of rules to control the privilege/permission context, the ability to assign a role to multiple privileges using the wildcard pattern, and the ability to overwrite a role-to-permission assignment using the higher priority rule.

To use the RBAC component, we must register available roles and create an association between the role and the permission. Use the same Bootloader and Spiral\Security\PermissionsInterface for this purpose. Once the Bootloader is activated, you can use Spiral\Core\GuardInterface to check the access to the specific permissions, the guard will resolve active Actor automatically via dynamic scope using Spiral\Security\GuardScope.

Here is an example of how to set up permissions and check if the Actor has access to the specific permission:

namespace App\Bootloader;

use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Core\Container;
use Spiral\Security\Actor\Actor;
use Spiral\Security\ActorInterface;
use Spiral\Security\PermissionsInterface;

class ActorBootloader extends Bootloader
{
    public function boot(Container $container, PermissionsInterface $rbac): void
    {
        $container->bindSingleton(ActorInterface::class, new Actor(['user']));

        $rbac->addRole('user');
        $rbac->associate('user', 'home.read');
    }
}

Accessing:

namespace App\Controller;

use Spiral\Security\GuardInterface;

class HomeController
{
    public function index(GuardInterface $guard): string
    {
        if (!$guard->allows('home.read')) {
            return 'can not read';
        }

        return 'can read';
    }
}

#Links and materials to read more:

1. Spiral Security - Role Based Access Control

#When to use them

Interceptors are a convenient way to intercept and modify the behavior of certain parts of the application, making it more functional and efficient, while keeping the domain-specific logic clean and maintainable. Here are some benefits of using interceptors:

• Separation of Concerns: Using interceptors allows you to keep the different parts of your application separate and organized. For example, you can use an interceptor to handle authentication without having to add that code to every single part of your application that requires authentication. This makes it a lot easier to understand and maintain your code.
• Reusability: With interceptors, you can write code once and use it in multiple parts of your application. This means you don't have to keep writing the same code over and over again, saving you time and reducing the likelihood of mistakes.
• Modularity: The ability to add, remove or replace interceptors without affecting the rest of the application makes it more flexible and easy to update.
• Performance: Interceptors can be used to optimize the performance of the application by caching responses, reducing the number of database queries, and more. This means your application will be faster, and less likely to slow down when a lot of users are accessing it at the same time.

Specific use cases:

• Logging: Interceptors can be used to log information about the application's operation. For example, you could create an interceptor that logs every database query that is executed, along with information about how long the query took to run. This can be useful for performance tuning and debugging.
• Caching: If your application retrieves data from a slow source (like a remote API or a large database), you could use an interceptor to cache the results of these operations. The interceptor would first check if the data is in the cache, and if so, return the cached data instead of performing the slow operation.
• Authentication and Authorization: Interceptors can be used to check if a user is authenticated and authorized to perform a certain operation. For example, before a user is allowed to update a record in the database, an interceptor could check if the user has the necessary permissions.
• Input Validation: You could use an interceptor to validate the inputs to a method or function. If the inputs are not valid, the interceptor could throw an exception or return an error, preventing the operation from being performed.
• Rate Limiting: If you want to limit how often a certain operation can be performed (for example, to prevent abuse or to control resource usage), you could use an interceptor to keep track of how often the operation is performed and throw an exception or return an error if the limit is exceeded.
• Transaction Management: In a database application, you could use an interceptor to manage database transactions. The interceptor could start a transaction before the operation is performed and commit the transaction after the operation is successful. If an error occurs during the operation, the interceptor could roll back the transaction.

#Links and materials to read more:

1. Spiral Interceptors

#Interceptors

One of the key features of Spiral is its support for interceptors, which can be used to add functionality to the application without modifying the core code of the application. This can help to keep your codebase more modular and maintainable. Interceptors work similarly to middleware in HTTP requests, in that they allow developers to add functionality to the application at various points in the processing flow. However, unlike middleware which is typically specific to HTTP requests, interceptors can be used to add functionality to a wide range of components.

Interceptors should implement the Spiral\Core\CoreInterceptorInterface interface, which requires them to define a process method. This method is called by the framework at specific points in the application's execution, such as before or after a controller action is invoked.

Here is an example of how to set up an interceptor:

namespace App\Integration\Database\Interceptor;

use Spiral\Core\CoreInterceptorInterface;
use Spiral\Core\CoreInterface;
use Cycle\Database\Exception\StatementException\ConnectionException;

final class DatabaseConnectionInterceptor implements CoreInterceptorInterface
{
    public function process(string $database, string $sql, array $parameters, CoreInterface $core): mixed
    {
        try {
            return $core->callAction($database, $sql, $parameters);
        } catch (ConnectionException $e) {
            // Try to reconnect...
            return $this->process('slave', $sql, $parameters, $core);
        }
    }
}

#Links and materials to read more:

1. Spiral Interceptors

#Setting Up Base Test

Before you start testing your Spiral application, you need to set up a base test. This is an abstract class that configures the environment for each test case. It initializes the application and sets up necessary services. After each test case, the application is destroyed to ensure that each test runs in a clean environment.

abstract class BaseTest extends TestCase
{
    /**
     * @var \\App
     */
    protected $app;

    public function setUp()
    {
        $root = dirname(__DIR__) . '/';

        $app = $this->app = \\App::init([
            'root'        => $root,
            'libraries'   => $root . 'vendor/',
            'application' => $root . 'app/',
        ], null, null, false);

        //Monolog love to write to CLI when no handler is set
        $this->app->logs->debugHandler(new NullHandler());
    }

    /**
     * This method performs full destroy of spiral environment.
     */
    public function tearDown()
    {
        if (class_exists('Mockery')) {
            //Mockery defines it's own static container to be destructed
            \\Mockery::close();
        }

        //Forcing destruction
        $this->app = null;

        gc_collect_cycles();
        clearstatcache();
    }
}

#Links and materials to read more:

1. Testing Application

#Testing HTTP Methods

Spiral provides a HttpTest class that allows you to emulate user requests, cookies, and sessions. This is useful for testing how your application responds to different HTTP methods like GET, POST, DELETE, and PUT.

class IndexTest extends HttpTest
{
    public function testSeeWelcome()
    {
        $response = $this->get('/');

        $this->assertSame(200, $response->getStatusCode());
        $this->assertContains('Welcome to Spiral Framework', (string)$response->getBody());
        $this->assertContains('welcome.dark.php', (string)$response->getBody());
    }
}

#Links and materials to read more:

1. Testing HTTP Methods

#Mocking Databases

For more realistic testing, you can mock your database. This involves pointing your target database to another driver, usually a runtime SQLite. This allows you to test your application code in a more realistic environment, but be aware that your tests might take longer to execute.

public function setUp()
{
    $root = dirname(__DIR__) . '/';

    $app = $this->app = \\App::init([
        'root'        => $root,
        'libraries'   => $root . 'vendor/',
        'application' => $root . 'app/',
    ], null, null, false);

    //Replace default database
    $this->app->dbal->addDatabase(new Database(
        $this->app->dbal->driver('runtime'),
        'default',
        'tests_'
    ));

    //Monolog love to write to CLI when no handler is set
    $this->app->logs->debugHandler(new NullHandler());

    //Schemas and seeds
    $this->app->console->run('orm:schema', ['-alter'=>true]);
    $this->app->console->run('app:seed');
}

#Links and materials to read more:

1. Testing Application

#Test Bootloaders

In some cases, you might want to replace the list of application bootloaders in your tests. This can be done by creating a child of the App class with the desired value.

class TestApplication extends App
{
    const LOAD = []; //Bootloads nothing, manual initialization is required
}

#Links and materials to read more:

1. Testing Application

#Testing

Testing is a critical aspect of software development, ensuring that your application behaves as expected and helps to prevent regressions when changes are made. The Spiral Framework provides a robust testing environment, making it easy to write and run tests for your application.

Spiral uses PHPUnit as its primary testing framework. It provides a FakeHttp class for making requests to your application and inspecting the responses, making it straightforward to test your HTTP controllers. It also offers functionality for testing file uploads, working with session data, and testing user authentication.

The testing environment in Spiral is flexible and powerful, designed to make it as easy as possible to ensure your application is working correctly.

#Deployment

Deploying a Spiral application can be a complex task, as it requires various steps to be performed in order to ensure that the application is properly configured and ready for production use. In this guide, we will go over several strategies for deploying an application, including basic file transfer, using source control, build scripts, and Docker builds.

#Links and materials to read more:

1. Deployment Guide

#Using the Serializer

Three serializers are available by default:

1. JsonSerializer - uses PHP functions json_encode and json_decode. It does not support data hydration to an object.
2. PhpSerializer - uses PHP functions serialize and unserialize.
3. CallbackSerializer- uses callbacks for serializing and deserializing data.

You can inject the serializer from a container using the SerializerInterface. It will refer to the default serializer. You can also use the SerializerManager to get a specific serializer by a serializer string key from config.

// Configuration for the serializer component
use Spiral\Core\Container\Autowire;
use Spiral\Serializer\Serializer\JsonSerializer;
use Spiral\Serializer\Serializer\PhpSerializer; 
use Spiral\Serializer\Serializer\CallbackSerializer;

return [
    'default' => 'json',
    'serializers' => [
        'json' => JsonSerializer::class,
        'serializer' => new Autowire(PhpSerializer::class),
        'callback' => new CallbackSerializer()
    ],
];

#Links and materials to read more:

1. Data Serialization

#Creating a Custom Serializer

You can create a custom serializer that implements the SerializerInterface. You need to implement 2 methods: the serialize method with the $payload parameter (and this method should return the serialized data) and the unserialize method, which in the parameters accepts serialized data $payload and optionally the name of the class or object $type into which the payload should be deserialized.

namespace App;

use Spiral\Serializer\SerializerInterface;

class CustomSerializer implements SerializerInterface
{
    public function serialize(mixed $payload): string|\Stringable
    {
        // your serialization logic goes here
    }

    public function unserialize(\Stringable|string $payload, object|string|null $type = null): mixed
    {
        // your deserialization logic goes here
    }
}

#Links and materials to read more:

1. Data Serialization

#Data Serialization

Data serialization is a process of converting the state of an object into a form that can be stored or transported. Spiral Framework provides a component for serializing and deserializing data. The component provides only the simplest serializers out of the box and may not cover all your use cases. But it provides an easy way to integrate serialization tools into the Spiral Framework or develop your solutions for serializing data in your application.

#Links and materials to read more:

1. Data Serialization

#Installation and Configuration

To use application metrics in Spiral, you first need to install the spiral/roadrunner-bridge package. Then, you can add the Spiral\RoadRunnerBridge\Bootloader\MetricsBootloader to the list of bootloaders. The metrics service does not require configuration in the application, but you must activate the service in .rr.yaml.

// Installation
// At first, you need to install the spiral/roadrunner-bridge package.
// Once the package is installed, you can add the Spiral\RoadRunnerBridge\Bootloader\MetricsBootloader to the list of bootloaders:

protected const LOAD = [
    // ...
    \Spiral\RoadRunnerBridge\Bootloader\MetricsBootloader::class,
    // ...
];

// Configuration
// The metrics service does not require configuration in the application. However, you must activate the service in .rr.yaml:

rpc:
  listen: tcp://127.0.0.1:6001

## ...

metrics:
  ## prometheus client address (path /metrics added automatically)
  address: 127.0.0.1:2112

#Links and materials to read more:

1. Application Metrics

#Tagged Metrics

Tagged (or labeled) metrics allow you to attach additional metadata to your metrics, which can be useful for filtering, grouping, and aggregating the data. This can increase granularity, improve organization, and simplify querying.

// Using tagged (also known as labeled) metrics allows you to attach additional metadata to your metrics, which can be useful for filtering, grouping, and aggregating the data.

// Using the .rr.yaml file:
metrics:
  address: 127.0.0.1:2112

  collect:
    registered_users:
      type: histogram
      help: "Total registered users counter."
      labels: [ "type" ]

// In the example, the registered_users metric is declared with a label called type. When adding data to the metric, you can specify the value for the type label, such as customer, admin, etc.

use Spiral\RoadRunner\Metrics\MetricsInterface; 

class UserRegistrationHandler
{
    public function __construct(
        private readonly MetricsInterface $metrics
    ) {
    }

    public function handle(User $user): void
    {
        // Store user in database

        $this->metrics->add('registered_users', 1, ['customer']);
        
        // or
        
        $this->metrics->add('registered_users', 1, ['admin']);
    }
}

#Links and materials to read more:

1. Application Metrics

#Application Metrics

Application metrics are crucial for keeping track of the performance and health of your application. Spiral Framework, in conjunction with the RoadRunner plugin, provides the ability to send application metrics to Prometheus, an open-source monitoring system. This allows you to collect, store, and analyze time series data such as application metrics. You can then use a tool like Grafana to visualize these metrics in real-time.

#Links and materials to read more:

1. Application Metrics

#Using attributes in interceptors

Interceptors in Spiral Framework are a powerful tool for adding functionality to your application without modifying the core code. They can be used to handle cross-cutting concerns like logging, caching, and more. Attributes can be used in conjunction with interceptors to further enhance their functionality.

For example, you can create an interceptor that logs slow database queries. You can use an attribute to specify which methods should be logged, and the interceptor can read this attribute and act accordingly. This allows you to control the behavior of the interceptor on a per-method basis, giving you fine-grained control over its behavior.

Here is an example of how to use attributes in an interceptor:

namespace App\Integration\Database\Interceptor;

use Psr\Log\LoggerInterface;
use Spiral\Core\CoreInterceptorInterface;
use Spiral\Core\CoreInterface;

class SlowQueryDetectorInterceptor implements CoreInterceptorInterface
{
    public function __construct(
        private readonly LoggerInterface $logger
    ) {
    }

    public function process(string $database, string $sql, array $parameters, CoreInterface $core): mixed
    {
        $startTime = \microtime(true);

        $result = $core->callAction($database, $sql, $parameters);
        
        $elapsed = \microtime(true) - $startTime;

        if ($elapsed > 0.1) {
            $this->logger->warning(
                'Slow query detected',
                [
                    'database' => $database,
                    'sql' => $sql,
                    'parameters' => $parameters,
                    'elapsed' => $elapsed
                ]
            );
        }

        return $result;
    }
}

#Links and materials to read more:

1. Interceptors in Spiral Framework

#Custom attributes

Attributes in PHP are a way to add metadata to classes, properties, functions, constants, and parameters. This metadata can be used to modify the behavior of the code at runtime. Spiral Framework supports the use of custom attributes to add additional functionality or modify the behavior of your application.

Attributes can be used in various parts of your application, such as controllers, services, and models. They can be used to define routing information, validation rules, and more. This allows you to keep your code clean and focused on its primary responsibilities, while the attributes handle the ancillary concerns.

#Links and materials to read more:

1. Attributes in Spiral Framework

#Translations

The Spiral i18n component, based on the symfony/translator package, provides interfaces for internationalization. This component is included in the web bundle by default. It allows you to translate your application into multiple languages, which is crucial for applications that aim to serve users from different regions and language backgrounds.

The i18n component automatically loads all locale files located in app/locale/{lang} directories. You can get a list of available locales and change the locale using the setLocale method. The framework supplies a default configuration automatically, but you can alter the configuration by creating the app/config/translator.php file.

#Links and materials to read more:

1. Translations in Spiral Framework

#Cloud Storage

Spiral offers a comprehensive solution for file storage and distribution through its spiral/storage and spiral/distribution components. The spiral/storage component provides powerful storage abstraction utilizing the capabilities of the Flysystem PHP package, offering convenient drivers for working with both local file systems and Amazon S3. The spiral/distribution component, which is integrated with the spiral/storage component, is responsible for generating public HTTP links for resources stored through the storage component.

To use the storage capabilities, you need to install the component and configure it. The installation process involves adding the Spiral\Storage\Bootloader\StorageBootloader to the list of bootloaders in your application.

// Installation
protected const LOAD = [
    // ...
    \Spiral\Storage\Bootloader\StorageBootloader::class,
    // ...
];

After installation, you need to configure the storage settings. The storage configuration file is located at app/config/storage.php by default. In this file, you can define the storage buckets and their drivers.

// Configuration
return [
    'buckets' => [
        'local' => [
            'driver' => LocalStorageDriver::class,
            'directory' => directory('root') . 'uploads',
            'visibility' => AdapterInterface::VISIBILITY_PUBLIC,
        ],
        's3' => [
            'driver' => S3StorageDriver::class,
            'region' => env('AWS_REGION'),
            'version' => 'latest',
            'credentials' => [
                'key' => env('AWS_KEY'),
                'secret' => env('AWS_SECRET'),
            ],
            'bucket' => env('AWS_BUCKET'),
            'prefix' => env('AWS_PREFIX'),
            'endpoint' => env('AWS_ENDPOINT'),
            'visibility' => AdapterInterface::VISIBILITY_PUBLIC,
        ],
    ],
];

#Links and materials to read more:

1. Spiral Storage Documentation

#Websockets

Websockets are a protocol that provides full-duplex communication channels over a single TCP connection. They are designed to be implemented in web browsers and web servers, but can be used by any client or server application. Websockets are an important part of the real-time web, enabling the development of interactive web applications with real-time, two-way communication.

In the context of the Spiral Framework, websockets are implemented using the spiral/roadrunner-bridge package and the Centrifugo server. The Centrifugo server is a scalable real-time messaging server in language-agnostic way. It works in conjunction with the RoadRunner server to handle websocket connections and communication.

The integration of Centrifugo with Spiral provides efficient management of real-time data transmission, making it an ideal solution for applications that require real-time updates and notifications. It also provides scalability, allowing for the easy expansion of your application as it grows. Centrifugo provides a powerful and flexible toolset that can be easily customized to meet the specific needs of your application.

To use websockets in your Spiral application, you need to install the spiral/roadrunner-bridge package and add the Spiral\RoadRunnerBridge\Bootloader\CentrifugoBootloader to the list of bootloaders in your application. //code

// Installation
protected const LOAD = [
    // ...
    \Spiral\RoadRunnerBridge\Bootloader\CentrifugoBootloader::class,
    // ...
];

After installation, you need to configure the communication between RoadRunner and Centrifugo by modifying the .rr.yaml file.

// Configuration for RoadRunner and Centrifugo communication
rpc:
  listen: tcp://0.0.0.0:6001

server:
  command: "php app.php"
  relay: pipes

centrifuge:
  proxy_address: "tcp://0.0.0.0:10001"
  grpc_api_address: "centrifugo:10000"

You also need to configure the Centrifugo server by creating a config.json file and specifying the communication settings between Centrifugo and RoadRunner.

In your Spiral application, you will need to create a centrifugo.php file in the app/config directory. In this file, you can specify services that will handle incoming events from the Centrifugo server, as well as any interceptors that should be applied to the events.

// Spiral application configuration for Centrifugo
use RoadRunner\Centrifugo\Request\RequestType;

return [
    'services' => [
        RequestType::Connect->value => ConnectService::class,
        RequestType::Subscribe->value => SubscribeService::class,
        RequestType::Refresh->value => RefreshService::class,
        RequestType::Publish->value => PublishService::class,
        RequestType::RPC->value => RPCService::class,
    ],
    'interceptors' => [
        RequestType::Connect->value => [
            Interceptor\AuthInterceptor::class,
        ],
        RequestType::Subscribe->value => [
            Interceptor\AuthInterceptor::class,
        ],
        RequestType::RPC->value => [
            Interceptor\AuthInterceptor::class,
        ],
        '*' => [
            Interceptor\TelemetryInterceptor::class,
        ],
    ],
];

#Links and materials to read more:

1. Websockets in Spiral Framework

#Ways of communication between microservices

When it comes to communication between microservices, there are several protocols that you can use, each with its own pros and cons.

1. HTTP/REST: This is a stateless protocol, which means each request from client to server must contain all the information needed to understand and process the request. It's simple and easy to use, but it may not be the most efficient for complex or high-volume microservices communication.

2. gRPC: This is a high-performance, open-source universal RPC framework developed by Google. It uses Protocol Buffers as its interface definition language, allowing you to define services and message types in .proto files. It's highly efficient and suitable for point-to-point real-time communication. However, it's more complex to set up and use compared to HTTP/REST.

3. GraphQL: This is a query language for APIs and a runtime for executing those queries with your existing data. It's highly flexible and allows clients to request exactly the data they need, reducing the amount of data that needs to be transferred. However, it can be more complex to set up and maintain compared to other options.

4. Message Queues (RabbitMQ, Kafka, etc.): These are used for asynchronous communication between microservices. They allow you to decouple your microservices and provide fault tolerance. However, they can add complexity to your system and require careful management to ensure reliability.

5. Event-Driven Architecture (EDA): This is a pattern that can be used to produce, detect, consume, and react to events. It's highly scalable and can provide real-time updates, but it can also add complexity to your system.

Choosing the right protocol depends on your specific use case and requirements. You might even use a combination of these protocols in a single application.

#Links and materials to read more:

1. HTTP/REST
2. gRPC
3. GraphQL
4. RabbitMQ
5. Kafka
6. Event-Driven Architecture

#Microservices

Microservices is an architectural style that structures an application as a collection of services that are highly maintainable and testable, loosely coupled, independently deployable, organized around business capabilities, and owned by a small team. The microservice architecture enables the rapid, frequent, and reliable delivery of large, complex applications. It also enables an organization to evolve its technology stack.

#Links and materials to read more:

1. Microservices in Spiral Framework

#gRPC

Using REST APIs for communication between microservices has been a common approach for many years. However, REST APIs have some limitations and challenges that can impact the performance, scalability, and reliability of your system. Switching from REST APIs to gRPC can help address these problems. The gRPC protocol provides an extremely efficient way of cross-service communication for distributed applications. The public toolkit includes instruments to generate client and server code-bases for many languages allowing developers to use the most optimal language for their task.

To use gRPC in your Spiral application, you need to install the spiral/roadrunner-bridge package and add the Spiral\RoadRunnerBridge\Bootloader\GRPCBootloader to the list of bootloaders in your application.

// Installation
protected const LOAD = [
    // ...
    \Spiral\RoadRunnerBridge\Bootloader\GRPCBootloader::class,
    \Spiral\RoadRunnerBridge\Bootloader\CommandBootloader::class,
    // ...
];

After installation, you need to configure the communication between RoadRunner and gRPC by modifying the .rr.yaml file and creating a grpc.php file in the app/config directory. In this file, you can specify services that will handle incoming events from the gRPC server.

// Configuration for RoadRunner and gRPC communication
server:
  command: "php app.php"

grpc:
  // GRPC address to listen
  listen: "tcp://0.0.0.0:9001"
  proto:
    - "proto/calculator.proto"

// Spiral application configuration for gRPC
return [
    /**
     * The path where generated DTO (Data Transfer Object) files will be stored.
     */
    'generatedPath' => directory('root') . '/GRPC',

    /**
     * The root dir for all proto files, where imports will be searched.
     */
    'servicesBasePath' => directory('root') . '/proto',

    /**
     * The path to the protoc-gen-php-grpc library.
     */
    'binaryPath' => directory('root').'/bin/protoc-gen-php-grpc',

    /**
     * An array of paths to proto files that should be compiled into PHP by the grpc:generate console command.
     */
    'services' => [
        //directory('root').'proto/calculator.proto',
    ],
];

#Links and materials to read more:

1. gRPC in Spiral Framework

#Temporal

Temporal is an open-source workflow engine that manages and executes reliable, durable, and fault-tolerant workflows in a distributed manner. The only way to use it in PHP is with RoadRunner, which makes it super easy to integrate your PHP app with Temporal.

Temporal allows you to write your workflows and activities in any supported language. For example, you could have a workflow written in PHP, but handle some of the activities with code written in Go or vice versa. This can be really helpful if you have a team with different language preferences, or if you want to take advantage of the strengths of different languages for different tasks.

Temporal is particularly useful in the following scenarios:

1. Long-running business processes: Temporal is excellent for managing processes that can take a long time to complete, where you need to maintain state in a reliable way. This could include processes like order fulfillment, payment processing, or user onboarding.

2. Reliable task scheduling and execution: Temporal can ensure that tasks are executed reliably, even in the face of server outages or software crashes. This makes it great for any scenario where you need to ensure a task is completed, regardless of what happens to the system.

3. Complex coordination of tasks: Temporal provides a framework for orchestrating complex sequences of tasks, including parallel execution, complex decision-making, and error handling. This is useful in scenarios like data processing, where you might need to coordinate a series of different tasks in a particular order.

4. Distributed transactions: If you need to perform a series of tasks across different services as part of a single transaction, Temporal can help. It can ensure that all tasks are completed successfully or that compensating transactions are executed if something goes wrong.

5. Testing and debugging: Temporal includes testing and debugging tools that make it easier to work with long-running workflows. You can replay workflows, inspect the state of a workflow at any point in time, and even write unit tests for your workflows.

#Links and materials to read more:

1. Temporal in Spiral Framework