Spiral

https://github.com/spiral/docs
Admin
Spiral is a robust PHP framework built for medium to large-sized enterprise applications, featuring...
Tokens:550,290
Snippets:4,247
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start Temporal development server with CLI

Source: https://github.com/spiral/docs/blob/3.16/docs/en/temporal/configuration.md

Start a local Temporal development server using the Temporal CLI. Requires the CLI to be installed first.

```terminal
temporal server start-dev
```

--------------------------------

### Installation prompts for consumer setup

Source: https://github.com/spiral/docs/blob/3.16/docs/en/cookbook/simple-queue-system.md

Shows the expected interactive prompts and answers when installing the Spiral app for a consumer. Selecting Yes for Queue and RoadRunner is required for the consumer setup.

```output
✔ Which application preset do you want to install? > Cli
✔ Create a default application structure and demo data? > No
✔ Do you want to use Queue component? > Yes
✔ Do you need RoadRunner? > Yes
```

--------------------------------

### Installer output when creating a Spiral project

Source: https://github.com/spiral/docs/blob/3.16/docs/en/start/installation.md

Example output from the `composer create-project` command, showing the installation progress and the interactive prompt to choose an application preset.

```output
Creating a "spiral/app" project at "./my-app"
Installing spiral/app (1.1.1)
  - Installing spiral/app (1.1.1): Extracting archive
Created project in /var/www/my-app
> Installer\Installer::install

  Which application preset do you want to install?
  [1] Web
  [2] Cli
  [3] gRPC
  Make your selection (1):
```

--------------------------------

### Manual storage setup with Bucket::fromAdapter

Source: https://github.com/spiral/docs/blob/3.16/docs/en/advanced/storage.md

Create a storage instance manually and add a bucket using an existing Flysystem adapter. Use this when the component is installed separately from the framework. The bucket is retrieved by name and used to write a file.

```php
$storage = new \Spiral\Storage\Storage();

$storage->add('example', \Spiral\Storage\Bucket::fromAdapter(
    new \League\Flysystem\Local\LocalFilesystemAdapter(__DIR__ . '/path/to/directory')
));

$file = $storage->bucket('example')
    ->write('file.txt', 'content');
```

--------------------------------

### Start RoadRunner server with ./rr serve

Source: https://github.com/spiral/docs/blob/3.16/docs/en/cookbook/simple-chat.md

Starts the RoadRunner server after installation. The application becomes available at http://127.0.0.1:8080 by default.

```terminal
cd realtime-chat

./rr serve
```

--------------------------------

### Install spiral/app with Composer

Source: https://github.com/spiral/docs/blob/3.16/docs/en/cookbook/quick-start.md

Run this command to create a new Spiral project using the default spiral/app bundle. The installer will prompt for various options; the recommended choices are shown in the following example.

```terminal
composer create-project spiral/app spiral-demo
```

--------------------------------

### Get file size

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/files.md

Get the file size. The example passes __DIR__ and dumps the size.

```php
dump($files->size(__DIR__));
```

--------------------------------

### Install protobuf extension via PECL

Source: https://github.com/spiral/docs/blob/3.16/docs/en/grpc/configuration.md

Install the protobuf PHP extension via PECL. The first command installs the latest version; if a Segmentation Fault occurs, use the second command to install version 3.10.0, which is recommended for stability.

```bash
sudo pecl install protobuf
```

```bash
sudo pecl install protobuf-3.10.0
```

--------------------------------

### Example HTTP config

Source: https://github.com/spiral/docs/blob/3.16/docs/en/testing/start.md

Example configuration for the 'http' config used in the testing examples. It defines basePath, headers, and middleware.

```php
return [
    'basePath'   => '/',
    'headers'    => [
        'Content-Type' => 'text/html; charset=UTF-8',
    ],
    'middleware' => [],
];
```

--------------------------------

### Recommended Spiral installer options for a CLI queue producer

Source: https://github.com/spiral/docs/blob/3.16/docs/en/cookbook/simple-queue-system.md

Shows the recommended installer options for a CLI application that pushes jobs to a queue. Selecting these options installs the necessary components for the tutorial.

```output
✔ Which application preset do you want to install? > Cli
✔ Create a default application structure and demo data? > No
✔ Do you need Cycle ORM? > No
✔ Do you want to use Queue component? > Yes
✔ Do you want to use Cache component? > No
✔ Do you want to use Mailer Component? > No
✔ Do you want to use Storage component? > No
✔ Do you need RoadRunner? > Yes
✔ Do you need the RoadRunner Metrics? > No
✔ Do you need the Temporal? > No
```

--------------------------------

### Install cycle/entity-behavior package

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/orm.md

Installs the cycle/entity-behavior package required for entity behaviors.

```bash
composer require cycle/entity-behavior
```

--------------------------------

### Install Xhprof extension with PECL

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/debug.md

Install the Xhprof extension via PECL. Run the channel update first, then install the package.

```terminal
pear channel-update pear.php.net
pecl install xhprof
```

--------------------------------

### Define routes with RoutingConfigurator in RoutesBootloader

Source: https://github.com/spiral/docs/blob/3.16/docs/en/http/routing.md

Define routes directly in the RoutesBootloader using the RoutingConfigurator's add method. The example adds a route named 'news.show' with pattern '/news/<id:int>', assigns it to the 'web' group, restricts it to GET requests, and maps it to the 'show' action of NewsController. Requires the RoutesBootloader to be in the LOAD section of the bootloaders list.

```php
namespace App\Application\Bootloader;

use Spiral\Bootloader\Http\RoutesBootloader as BaseRoutesBootloader;
use Spiral\Router\Loader\Configurator\RoutingConfigurator;

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

--------------------------------

### Install spiral/grpc-client via Composer

Source: https://github.com/spiral/docs/blob/3.16/resources/releases/grpc-client/1.0.md

Install the spiral/grpc-client package with the -W flag to also update dependencies. Requires the gRPC PHP extension to be installed.

```bash
composer require spiral/grpc-client -W
```

--------------------------------

### Install Keeper with Composer

Source: https://github.com/spiral/docs/blob/3.16/docs/en/keeper/intro.md

Run this command to install the spiral/keeper package. This is the first step in setting up Keeper.

```terminal
composer require spiral/keeper
```

--------------------------------

### Create Bootloader example with output

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/scaffolding.md

Example of creating a Bootloader named 'App' and the resulting generated file. The command output is the AppBootloader class with empty bindings, singletons, dependencies, and init/boot methods.

```terminal
php app.php create:bootloader App
```

```php
declare(strict_types=1);

namespace App\Application\Bootloader;

use Spiral\Boot\Bootloader\Bootloader;

final class AppBootloader extends Bootloader
{
    protected const BINDINGS = [];
    protected const SINGLETONS = [];
    protected const DEPENDENCIES = [];

    public function init(): void
    {
    }

    public function boot(): void
    {
    }
}
```

--------------------------------

### Install and configure the demo project

Source: https://github.com/spiral/docs/blob/3.16/docs/en/cookbook/quick-start.md

Run these commands in order to install and configure the demo project. The first command fetches the RoadRunner binary, the next two initialize and run database migrations, and the last command runs the application configuration with verbose output.

```terminal
./vendor/bin/rr get
php app.php migrate:init
php app.php migrate
php app.php configure -vv
```

--------------------------------

### Get file permissions as integer

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/files.md

Get the file/directory permissions as an integer. The example passes __FILE__.

```php
dump($files->getPermissions(__FILE__)); // int
```

--------------------------------

### boot() method with compiled configuration

Source: https://github.com/spiral/docs/blob/3.16/docs/en/framework/bootloaders.md

Use the boot() method to configure services using finalized configuration and to set up integrations between components. It runs after all init() methods complete, supports dependency injection, and can receive compiled configuration objects. This example injects GithubConfig and HttpBootloader to create a client and add middleware.

```php
final class GithubClientBootloader extends Bootloader
{
    public function boot(
        GithubConfig $config,
        HttpBootloader $http
    ): void {
        // Configuration is now compiled and ready
        $client = new GithubClient($config->getAccessToken());
        
        // Other bootloaders are initialized
        $http->addMiddleware(GithubAuthMiddleware::class);
    }
}
```

--------------------------------

### Get file MD5 hash

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/files.md

Get the MD5 hash of a file. The example passes a filename string.

```php
dump($files->md5('filename'));
```

--------------------------------

### Install spiral/sapi-bridge package

Source: https://github.com/spiral/docs/blob/3.16/docs/en/cookbook/migration-from-v2.md

Install the spiral/sapi-bridge package to provide an emitter implementation for Spiral\Http\EmitterInterface, for example when using Spiral with nginx.

```terminal
composer require spiral/sapi-bridge
```

--------------------------------

### Get file extension without dot

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/files.md

Get the file extension without the leading dot. The example passes __FILE__.

```php
dump($files->extension(__FILE__)); // without leading "."
```

--------------------------------

### Initialize kernel with MyApp::create and run

Source: https://github.com/spiral/docs/blob/3.16/docs/en/framework/kernel.md

Initializes the kernel with the static `create` method, passing directories and disabling the error handler. Runs the application with the default environment and dumps the registered directories.

```php
$myapp = MyApp::create(
    directories: [
        'root' => __DIR__,
    ],
    handleErrors: false // do not mount error handler
);

$myapp->run(environment: null); // use default env 

\dump($myapp->get(\Spiral\Boot\DirectoriesInterface::class)->getAll());
```

--------------------------------

### Spiral installer recommended options

Source: https://github.com/spiral/docs/blob/3.16/docs/en/cookbook/quick-start.md

These are the recommended answers to the Spiral installer prompts for this tutorial. Selecting these options sets up the application with Web preset, Cycle ORM with Doctrine Collections, Spiral Validator, Stempler, and Data Grid, while disabling other components.

```terminal
✔ Which application preset do you want to install? > Web
✔ Create a default application structure and demo data? > No
✔ Would you like to use SAPI? > No
✔ Do you need Cycle ORM? > Yes
✔ Which Collections do you want to use with Cycle ORM? > Doctrine Collections
✔ Which validator component do you want to use? > Spiral Validator
✔ Do you want to use Queue component? > No
✔ Do you want to use Cache component? > No
✔ Do you want to use Mailer Component? > No
✔ Do you want to use Storage component? > No
✔ Which template engine do you want to use? > Stempler
✔ Do you need Data Grid? > Yes
✔ Do you want to use the Event Dispatcher? > No
✔ Do you need a cron jobs scheduler? > No
✔ Do you need Translator? > No
✔ Do you need the Temporal? > No
✔ Do you need the RoadRunner Metrics? > No
✔ Do you need the Sentry? > No
```

--------------------------------

### Application entry point app.php

Source: https://github.com/spiral/docs/blob/3.16/docs/en/framework/dispatcher.md

Entry point app.php that creates the kernel, runs it, and calls serve() to execute the appropriate dispatcher based on the environment. Exits with the returned code.

```php
use App\Application\Kernel;

\mb_internal_encoding('UTF-8');
\error_reporting(E_ALL | E_STRICT ^ E_DEPRECATED);
\ini_set('display_errors', 'stderr');

require __DIR__ . '/vendor/autoload.php';
$app = Kernel::create(
    directories: ['root' => __DIR__],
)->run();

$code = (int)$app->serve();  // <========== Will run the appropriate dispatcher based on the current environment
exit($code);
```

--------------------------------

### Console configuration file example

Source: https://github.com/spiral/docs/blob/3.16/docs/en/console/configuration.md

Example of the console configuration file located at app/config/console.php. It shows the available configuration keys: name, version, commands, configure, and update.

```php
return [
     // application name
     'name'      => null,
     
     // application version
     'version'   => null,
     
     // list of application commands (if auto-discover disabled)
     'commands'  => [],
     
     // list of commands and sequences to run in `app configure`
     'configure' => [],
     
     // list of commands and sequences to run in `app update`
     'update'    => []
];
```

--------------------------------

### Test HomeController with FakeHttp GET request

Source: https://github.com/spiral/docs/blob/3.16/docs/en/testing/http.md

Shows a complete test case for a HomeController using FakeHttp to send a GET request to '/' and assert a 200 OK response. The test sets up a FakeHttp instance in setUp() and uses the get() method with assertOk().

```php
namespace Tests\Feature;

use Spiral\Testing\Http\FakeHttp;
use Tests\TestCase;

final class HomeControllerTest extends TestCase
{
    private FakeHttp $http;

    protected function setUp(): void
    {
        parent::setUp();
        $this->http = $this->fakeHttp();
    }

    public function testIndex(): void
    {
        $response = $this->http->get('/');
        $response->assertOk();
    }
}

```

--------------------------------

### Install gRPC Go dependencies

Source: https://github.com/spiral/docs/blob/3.16/docs/en/grpc/client.md

Install the gRPC Go toolkit and the protoc-gen-go plugin using the Go package manager. Required before compiling .proto files or creating a client.

```bash
go get -u google.golang.org/grpc
go get -u github.com/golang/protobuf/protoc-gen-go
```

--------------------------------

### Create a bootloader with the scaffolding command

Source: https://github.com/spiral/docs/blob/3.16/docs/en/framework/bootloaders.md

Run this command to generate a new bootloader class. It creates `app/src/Application/Bootloader/GithubClientBootloader.php`.

```terminal
php app.php create:bootloader GithubClient
```

--------------------------------

### Get specific serializer by key with SerializerManager

Source: https://github.com/spiral/docs/blob/3.16/docs/en/advanced/serializer.md

Use SerializerManager to retrieve a specific serializer by its string key from the configuration. The example shows how to get the 'json' and 'serializer' serializers and use them to serialize and unserialize data.

```php
namespace App\Service;

use Spiral\Serializer\SerializerManager;

class MyService
{
    public function __construct(
        private readonly SerializerManager $serializer,
    ) {
    }

    public function someMethod(): void
    {
        $serialized = $this->serializer->getSerializer('json')->serialize(['some' => 'data']);
        $array = $this->serializer->getSerializer('json')->unserialize($serialized);

        $serialized = $this->serializer->getSerializer('serializer')->serialize(['some' => 'data']);
        $array = $this->serializer->getSerializer('serializer')->unserialize($serialized);
    }
}
```

--------------------------------

### Bootstrap Rendering Setup in Prototyped HomeController

Source: https://github.com/spiral/docs/blob/3.16/docs/en/views/stempler.md

Uses PrototypeTrait to get ViewsInterface and render a view with the given data.

```php
namespace App\Endpoint\Web;

use Spiral\Prototype\Traits\PrototypeTrait;

class HomeController
{
    use PrototypeTrait;

    public function index(): string
    {
        return $this->views->render('welcome', [
            'name' => 'John',
        ]);
    }
}

```

--------------------------------

### Dynamic bootloading with BootloadManagerInterface::bootload()

Source: https://github.com/spiral/docs/blob/3.16/docs/en/framework/bootloaders.md

Use this PHP example to conditionally load bootloaders at runtime based on environment variables and feature flags. It demonstrates the `bootload()` method of `BootloadManagerInterface` with different bootloader sets for production and local environments. Note that dynamically loaded bootloaders cannot have `init()` methods or `#[InitMethod]` attributes because the initialization phase has already completed.

```php
use Spiral\Boot\BootloadManagerInterface;

class AppBootloader extends Bootloader
{
    public function boot(
        BootloadManagerInterface $bootloadManager, 
        EnvironmentInterface $env
    ): void {
        // Load debug tools only when DEBUG is enabled
        if ($env->get('DEBUG')) {
            $bootloadManager->bootload([
                DebugBootloader::class,
                ProfilerBootloader::class,
            ]);
        }
        
        // Load feature bootloaders based on feature flags
        if ($this->isFeatureEnabled('new-api')) {
            $bootloadManager->bootload([
                NewApiBootloader::class,
            ]);
        }
        
        // Load different bootloaders per environment
        match($env->get('APP_ENV')) {
            'production' => $bootloadManager->bootload([
                ProductionCacheBootloader::class,
                ProductionLoggingBootloader::class,
            ]),
            'local' => $bootloadManager->bootload([
                DevToolsBootloader::class,
                LocalCacheBootloader::class,
            ]),
            default => null,
        };
    }
}
```

--------------------------------

### Get specific storage with CacheStorageProviderInterface

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/cache.md

Inject a specific cache storage by its string key using CacheStorageProviderInterface. The example retrieves the 'user-data' storage and assigns it to a CacheInterface property.

```php
namespace App\Service;

use Spiral\Cache\CacheStorageProviderInterface;

class UserService
{
    private readonly CacheInterface $cache;
  
    public function __construct(CacheStorageProviderInterface $provider) 
    {
        $this->cache = $provider->storage('user-data');
    }

    public function find(int $id): User
    {
        //...
    }
}
```

--------------------------------

### Using #[InitMethod] with priorities in a bootloader

Source: https://github.com/spiral/docs/blob/3.16/docs/en/framework/bootloaders.md

Use this bootloader to split initialization logic into focused methods with fine-grained control over execution order. Methods marked with #[InitMethod] run during the initialization phase, support dependency injection, and can be prioritized (higher runs first). The example shows three methods with priorities 10, 0, and -10 to control the order of driver registration, connection binding, and optional extensions.

```php
use Spiral\Boot\Attribute\InitMethod;

final class DatabaseBootloader extends Bootloader
{
    // Critical: runs first
    #[InitMethod(priority: 10)]
    public function registerDrivers(DatabaseManager $manager): void
    {
        $manager->addDriver('mysql', MySQLDriver::class);
        $manager->addDriver('postgres', PostgresDriver::class);
    }
    
    // Normal: runs after high priority
    #[InitMethod]
    public function registerConnections(Container $container): void
    {
        $container->bindSingleton(
            ConnectionInterface::class,
            DefaultConnection::class
        );
    }
    
    // Low priority: runs last
    #[InitMethod(priority: -10)]
    public function registerExtensions(): void
    {
        // Optional extensions that depend on core setup
    }
}
```

--------------------------------

### Register before callback with schedule->before()

Source: https://github.com/spiral/docs/blob/3.16/docs/en/advanced/scheduler.md

Registers a callback that runs before the scheduled task executes, useful for preparation or setup. The callback receives a Notifier instance and sends a message before the task starts.

```php
$schedule->command('backup:run')
   ->everyFiveMinutes()
   ->before(static fn(Notifier $notifier) => $notifier->send('Starting backup...'));
   -> ...;
```

--------------------------------

### Configure Temporal client with TLS, auth, and retry options

Source: https://github.com/spiral/docs/blob/3.16/docs/en/temporal/configuration.md

Advanced client configuration example. Shows TLS, auth token, custom namespace/identity, and RPC retry options.

```php
use Spiral\TemporalBridge\Config\TlsConfig;
use Spiral\TemporalBridge\Config\ConnectionConfig;
use Spiral\TemporalBridge\Config\ClientConfig;
use Temporal\Client\ClientOptions;
use Temporal\Client\Common\RpcRetryOptions;
use Temporal\Client\GRPC\Context;

return [
    // ...
    'clients' => [
        'default' => new ClientConfig(
            connection: new ConnectionConfig(
                address: 'foo-bar-default.baz.tmprl.cloud:7233',
                tls: new TlsConfig(),
                authToken: 'my-secret-token',
            ),
            options: (new ClientOptions())
                ->withNamespace('default')
                ->withIdentity('customer-service'),
            context: Context::default()
                ->withTimeout(4.5)
                ->withRetryOptions(
                    RpcRetryOptions::new()
                        ->withMaximumAttempts(5)
                        ->withInitialInterval(3)
                        ->withMaximumInterval(10)
                        ->withBackoffCoefficient(1.6)
                ),
];
```

--------------------------------

### Access directory paths with DirectoriesInterface

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/files.md

Access directory paths by injecting DirectoriesInterface and calling get() with the directory key. This example retrieves 'uploadDir' and appends a filename to build a file path.

```php
use Spiral\Boot\DirectoriesInterface;

final class UploadService {
    public function __construct(
        private readonly DirectoriesInterface $dirs
    ) {}
    
    public function store(UploadedFile $file) {
        $filePath = $this->dirs->get('uploadDir') . $file->getFilename();
        // ...
    }
}
```

--------------------------------

### Execution order of bootloader methods

Source: https://github.com/spiral/docs/blob/3.16/docs/en/framework/bootloaders.md

This ordered list shows the complete execution sequence of bootloader methods. It clarifies that all #[InitMethod] methods run before any #[BootMethod] methods, and that traditional init() and boot() methods are interleaved according to their priority. Use this to understand the global ordering across all bootloaders.

```text
1. #[InitMethod(priority: 10)]  ← Highest priority init methods
2. #[InitMethod(priority: 0)]   ← Default priority init methods  
3. #[InitMethod(priority: -10)] ← Lowest priority init methods
4. init()                       ← Traditional init method
5. #[BootMethod(priority: 10)]  ← Highest priority boot methods
6. #[BootMethod(priority: 0)]   ← Default priority boot methods
7. #[BootMethod(priority: -10)] ← Lowest priority boot methods
8. boot()                       ← Traditional boot method
```

--------------------------------

### Dynamically select serializer with SerializerManager

Source: https://github.com/spiral/docs/blob/3.16/docs/en/cookbook/migration-from-v2.md

Use SerializerManager to get a serializer based on runtime options (e.g., format). The example shows comments for possible format values like 'json' or 'xml'.

```php
class Queue 
{
    public function __construct(
        private readonly PipelineInterface $pipeline,
        private readonly \Spiral\Serializer\SerializerManager $manager
    ) {}

    public function push(array $payload, Options $options): void
    {
        // $options->format = 'json'
        // $options->format = 'xml'
        // ...

        $this->pipeline->push(
            $this-manager
                ->getSerializer($options->format)
                ->serialize($payload)
        );
    }
}
```

--------------------------------

### Create controller with actions list and generated output

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/scaffolding.md

Command to create a controller with multiple actions using the `-a` option, followed by the generated `UserController` class containing methods for `index`, `show`, `create`, `update`, and `delete`. Each method includes a `Route` attribute placeholder.

```bash
php app.php create:controller User \
      -a index \
      -a show \
      -a create \
      -a update \
      -a delete
```

```php
declare(strict_types=1);

namespace App\Endpoint\Web;

use Psr\Http\Message\ResponseInterface;
use Spiral\Router\Annotation\Route;

class UserController
{
    /**
     * Please, don't forget to configure the Route attribute or remove it and register the route manually.
     */
    #[Route(route: 'path', name: 'name')]
    public function index(): ResponseInterface
    {
    }

    /**
     * Please, don't forget to configure the Route attribute or remove it and register the route manually.
     */
    #[Route(route: 'path', name: 'name')]
    public function show(): ResponseInterface
    {
    }

    /**
     * Please, don't forget to configure the Route attribute or remove it and register the route manually.
     */
    #[Route(route: 'path', name: 'name')]
    public function create(): ResponseInterface
    {
    }

    /**
     * Please, don't forget to configure the Route attribute or remove it and register the route manually.
     */
    #[Route(route: 'path', name: 'name')]
    public function update(): ResponseInterface
    {
    }

    /**
     * Please, don't forget to configure the Route attribute or remove it and register the route manually.
     */
    #[Route(route: 'path', name: 'name')]
    public function delete(): ResponseInterface
    {
    }
}

```

--------------------------------

### init() method with dependency injection

Source: https://github.com/spiral/docs/blob/3.16/docs/en/framework/bootloaders.md

Use the init() method to set configuration defaults before other bootloaders read them. It runs first, before any boot() method, and supports dependency injection through method parameters. This example injects EnvironmentInterface to read environment variables and sets defaults via ConfiguratorInterface.

```php
final class GithubClientBootloader extends Bootloader
{
    public function __construct(
        private readonly ConfiguratorInterface $config
    ) {}

    public function init(EnvironmentInterface $env): void 
    {
        // Set defaults before configuration is accessed
        $this->config->setDefaults(GithubConfig::CONFIG, [
            'access_token' => $env->get('GITHUB_ACCESS_TOKEN'),
            'secret' => $env->get('GITHUB_SECRET'),
            'timeout' => 30,
        ]);
    }
}
```

--------------------------------

### Add route-specific middleware via Route attribute

Source: https://github.com/spiral/docs/blob/3.16/docs/en/http/middleware.md

Add middleware to a route using the Spiral\Router\Annotation\Route attribute. The 'middleware' property accepts an array of middleware classes. This example applies MyMiddleware to the 'index' route with GET method.

```php
namespace App\Endpoint\Web;

use Spiral\Router\Annotation\Route;
use App\Endpoint\Web\Middleware\MyMiddleware;

class HomeController
{
    #[Route(route: '/', name: 'index', methods: 'GET', middleware: [MyMiddleware::class])] 
    public function index(): string
    {
        // ...
    }
}
```

--------------------------------

### Get single class attribute with firstClassMetadata()

Source: https://github.com/spiral/docs/blob/3.16/docs/en/advanced/attributes.md

Retrieves the first matching class attribute of a specific type using firstClassMetadata(). Returns null if no matching attribute is found, and the example checks for null before accessing the table name.

```php
use Cycle\Annotated\Annotation\Entity;

$reflection = new \ReflectionClass(User::class);

// Get first Entity attribute or null
$entity = $reader->firstClassMetadata($reflection, Entity::class); 
if ($entity !== null) {
    echo $entity->getTable();
}
```

--------------------------------

### Create file at Storage, Bucket, and File levels

Source: https://github.com/spiral/docs/blob/3.16/docs/en/advanced/storage.md

Shows three levels of storage operations: Storage, Bucket, and File. At the Storage level, pass a URI like 'bucket://example.txt'; at the Bucket level, pass only the file name; at the File level, no additional arguments are needed. The example creates the same file 'example.txt' in three different ways.

```php
use Spiral\Storage\StorageInterface;

class UploadController
{
    public function createFile(StorageInterface $storage): array
    {
        $result = [];
        
        // 1. Storage level
        $result[] = $storage->create('bucket://example.txt');

        // 2. Bucket level
        $result[] = $storage->bucket('bucket')
            ->create('example.txt');

        // 3. File level
        $result[] = $storage->bucket('bucket')
            ->file('example.txt')
            ->create();

        return $result;
    }
}
```

--------------------------------

### docker-compose.yml for Spiral application

Source: https://github.com/spiral/docs/blob/3.16/docs/en/start/deployment.md

Example `docker-compose.yml` that starts the application container. It maps port 8080 and sets environment variables like `DEBUG` and `APP_ENV`; you can manage these via external `.env` files instead of creating them inside the container.

```yaml
version: '3'
services:
  app:
    image: my-application:1.0
    ports:
      - "8080:8080"
    environment:
      - DEBUG=false
      - APP_ENV=production
      - ...
```

--------------------------------

### Provision server with dep provision

Source: https://github.com/spiral/docs/blob/3.16/docs/en/start/deployment.md

Provisions the server using the root user because the host does not have a deployer user yet. Deployer asks questions about PHP version and database type, then configures the server and creates the deployer user. Provisioning takes about 5 minutes and installs everything needed to run a website at deploy_path.

```terminal
dep provision -o remote_user=root
```

--------------------------------

### Read function attributes with getFunctionMetadata()

Source: https://github.com/spiral/docs/blob/3.16/docs/en/advanced/attributes.md

Reads attributes from methods and functions using getFunctionMetadata() and firstFunctionMetadata(). The example shows how to get all method attributes, filter by a specific type (Route), and retrieve the first matching attribute, accessing its path and methods.

```php
use Spiral\Router\Annotation\Route;

$reflection = new \ReflectionMethod(UserController::class, 'list');

// Get all method attributes
$attributes = $reader->getFunctionMetadata($reflection);

// Get specific attribute type
$routes = $reader->getFunctionMetadata($reflection, Route::class);

// Get first matching attribute
$route = $reader->firstFunctionMetadata($reflection, Route::class);
if ($route !== null) {
    echo $route->getPath(); // /users
    var_dump($route->getMethods()); // ['GET']
}
```

--------------------------------

### Read property attributes with getPropertyMetadata()

Source: https://github.com/spiral/docs/blob/3.16/docs/en/advanced/attributes.md

Reads attributes from class properties using getPropertyMetadata() and firstPropertyMetadata(). The example shows how to get all property attributes, filter by a specific type (Column), and retrieve the first matching attribute, accessing its type and nullability.

```php
use Cycle\Annotated\Annotation\Column;

$reflection = new \ReflectionProperty(User::class, 'email');

// Get all property attributes
$attributes = $reader->getPropertyMetadata($reflection);

// Get specific attribute type
$columns = $reader->getPropertyMetadata($reflection, Column::class);

// Get first matching attribute
$column = $reader->firstPropertyMetadata($reflection, Column::class);
if ($column !== null) {
    echo $column->getType(); // string
    var_dump($column->isNullable()); // false
}
```

--------------------------------

### Run Go client

Source: https://github.com/spiral/docs/blob/3.16/docs/en/grpc/client.md

Runs the Go client created in the previous step. Assumes the client code is in main.go.

```bash
go run main.go
```

--------------------------------

### Get command help with php app.php help current:date

Source: https://github.com/spiral/docs/blob/3.16/docs/en/start/cli-basics.md

Run the help command to display the command's signature, description, arguments, and options. The output shows the default format and available global options.

```terminal
php app.php help current:date
```

```output
[33mDescription:[39m
  Get current date

[33mUsage:[39m
  current:date [<format>]

[33mArguments:[39m
  [32mformat[39m                Date format[33m [default: "Y-m-d"][39m

[33mOptions:[39m
  [32m-h, --help[39m            Display help for the given command. When no command is given display help for the [32mlist[39m command
  [32m-q, --quiet[39m           Do not output any message
  [32m-V, --version[39m         Display this application version
  [32m    --ansi|--no-ansi[39m  Force (or disable --no-ansi) ANSI output
  [32m-n, --no-interaction[39m  Do not ask any interactive question
  [32m-v|vv|vvv, --verbose[39m  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
```

--------------------------------

### Symfony Var Dumper server console output

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/debug.md

Example console output from the Symfony Var Dumper server after starting it and running app.php. It shows the server listening on tcp://127.0.0.1:9912 and two dumped values: null and an App\Service\Site\Site object with its properties.

```terminal
./vendor/bin/var-dump-server

Symfony Var Dumper Server
=========================
 [OK] Server listening on tcp://127.0.0.1:9912
 // Quit the server with CONTROL-C.

$ app.php
---------
 -------- ---------------------------------------------------------
  date     Fri, 18 Aug 2023 11:54:44 +0000
  source   SimpleController.php on line 36
  file     app/src/Interfaces/Http/Controller/SimpleController.php
 -------- ---------------------------------------------------------
null

 -------- ---------------------------------------------------------
  date     Fri, 18 Aug 2023 11:54:44 +0000
  source   SimpleController.php on line 37
  file     app/src/Interfaces/Http/Controller/SimpleController.php
 -------- ---------------------------------------------------------
App\Service\Site\Site^ {#1260
  -theme: "default"
  -docs: App\Service\Site\Docs^ {#1269
    -defaultVersion: "3.5"
    -defaultLanguage: "en"
  }
  -host: "127.0.0.1"
}

```

--------------------------------

### Document controller methods with OpenAPI attributes

Source: https://github.com/spiral/docs/blob/3.16/docs/en/http/openapi.md

Add OpenAPI attributes to controller methods to generate API documentation. The example shows a UserController with GET and POST routes, using OA\Tag, OA\Get, OA\Post, and related attributes to define operations, parameters, and responses.

```php
<?php

declare(strict_types=1);

namespace App\Endpoint\Web;

use OpenApi\Attributes as OA;
use Spiral\Router\Annotation\Route;

#[OA\Tag(name: 'Users', description: 'User management')]
class UserController
{
    #[Route(route: '/api/users', name: 'users.list', methods: 'GET')]
    #[OA\Get(
        path: '/api/users',
        operationId: 'users.list',
        summary: 'List users',
        tags: ['Users'],
        parameters: [
            new OA\QueryParameter(
                name: 'page',
                description: 'Page number',
                schema: new OA\Schema(type: 'integer', default: 1)
            ),
        ],
        responses: [
            new OA\Response(
                response: 200,
                description: 'Success',
                content: new OA\JsonContent(
                    properties: [
                        new OA\Property(
                            property: 'data',
                            type: 'array',
                            items: new OA\Items(ref: '#/components/schemas/User')
                        ),
                    ]
                )
            ),
        ]
    )]
    public function list(): array
    {
        // Implementation
    }

    #[Route(route: '/api/users', name: 'users.create', methods: 'POST')]
    #[OA\Post(
        path: '/api/users',
        operationId: 'users.create',
        summary: 'Create user',
        requestBody: new OA\RequestBody(
            required: true,
            content: new OA\JsonContent(ref: CreateUserFilter::class)
        ),
        tags: ['Users'],
        responses: [
            new OA\Response(
                response: 201,
                description: 'Created',
                content: new OA\JsonContent(ref: '#/components/schemas/User')
            ),
        ]
    )]
    public function create(CreateUserFilter $filter): array
    {
        // Implementation
    }
}
```

--------------------------------

### Configure and start gRPC server

Source: https://github.com/spiral/docs/blob/3.16/docs/en/grpc/service.md

Configures the gRPC server in .rr.yaml to listen on tcp://0.0.0.0:9001 and loads the proto/pinger.proto file. Then starts the server with the ./rr serve command.

```yaml
grpc:
  listen: tcp://0.0.0.0:9001
  proto:
    - "proto/pinger.proto"
```

```terminal
./rr serve
```

--------------------------------

### Singleton attribute usage for ConfigurationManager

Source: https://github.com/spiral/docs/blob/3.16/docs/en/container/attributes.md

Use #[Singleton] to ensure a single instance of a class is shared across the application. The example defines a ConfigurationManager that loads a configuration file once in the constructor, and the get method provides access to its settings. It is useful for configuration managers, database connections, or loggers.

```php
use Spiral\Core\Attribute\Singleton;

#[Singleton]
final class ConfigurationManager
{
    private readonly array $config;

    public function __construct()
    {
        $this->config = parse_ini_file('config.ini');
    }

    public function get(string $key)
    {
        return $this->config[$key] ?? null;
    }
}
```

--------------------------------

### Register booting callback via $app->booting or bootloader init

Source: https://github.com/spiral/docs/blob/3.16/docs/en/framework/kernel.md

Two ways to register a `booting` callback: directly on the application instance after creation, or inside a bootloader's `init` method. The callback runs before the framework bootloaders in the `LOAD` section are booted.

```php
$app = MyApp::create(
    directories: ['root' => __DIR__]
);

$app->booting(function () {
    // ...
});

$app->run();
```

```php
namespace App\Application\Bootloader;

use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Boot\KernelInterface;

class AppBootloader extends Bootloader
{
    public function init(KernelInterface $app): void
    {
        $app->booting(function () {
            // ...
        });
    }
}
```

--------------------------------

### Implement QueueInterface for a custom Redis queue driver

Source: https://github.com/spiral/docs/blob/3.16/docs/en/queue/configuration.md

Implements the Spiral\Queue\QueueInterface to create a custom queue driver. The push method serializes the payload, generates a job ID, and pushes it to the Redis broker before returning the ID. This example is a starting point for a fake driver and requires the Redis extension and a serializer registry.

```php
namespace App\Infrastructure\Queue;

use Spiral\Queue\SerializerRegistryInterface;
use Spiral\Queue\QueueInterface;

final class RedisQueue implements QueueInterface
{
    public function __construct(
        private readonly SerializerRegistryInterface $redis,
        private readonly Redis $redis,
        private readonly string $server,
        private readonly string $queueName,
    ) {
    }

    public function push(string $name, array $payload = [], OptionsInterface $options = null): string
    {
        $payload = $this->serializerRegistry->getSerializer($name)->serialize($payload);
        
        $id = // generate job id
        
        // Push job to the redis broker and return job id
        $this->redis->...
        
        return $id;
    }
}
```

--------------------------------

### Authentication interceptor and usage in ConnectService

Source: https://github.com/spiral/docs/blob/3.16/docs/en/websockets/interceptors.md

The AuthenticatorInterceptor checks the 'authToken' field in the request data, loads the token, and if invalid returns a 403 error. It then starts an AuthContext and runs the handler within a scope that binds AuthContextInterface. The ConnectService example shows how to use the interceptor by checking authentication and responding with a ConnectResponse, throwing an exception if not authenticated.

```php
namespace App\Endpoint\Centrifugo\Interceptor;

use Psr\EventDispatcher\EventDispatcherInterface;
use RoadRunner\Centrifugo\Request\RequestInterface;
use Spiral\Auth\ActorProviderInterface;
use Spiral\Auth\AuthContext;
use Spiral\Auth\AuthContextInterface;
use Spiral\Auth\TokenStorageInterface;
use Spiral\Core\Scope;
use Spiral\Interceptors\Context\CallContextInterface;
use Spiral\Interceptors\HandlerInterface;
use Spiral\Interceptors\InterceptorInterface;
use Spiral\Core\ScopeInterface;
use Spiral\Prototype\Traits\PrototypeTrait;

final class AuthenticatorInterceptor implements InterceptorInterface
{
    use PrototypeTrait;

    public function __construct(
        private readonly ScopeInterface $scope,
        private readonly ActorProviderInterface $actorProvider,
        private readonly TokenStorageInterface $authTokens,
        private readonly ?EventDispatcherInterface $eventDispatcher = null,
    ) {}

    public function intercept(CallContextInterface $context, HandlerInterface $handler): mixed
    {
        $request = $context->getArguments()[0];
        \assert($request instanceof RequestInterface);

        $authToken = $request->getData()['authToken'] ?? null;
        $token = $authToken === null ? null : $this->authTokens->load($authToken);

        if ($token === null) {
            $request->error(403, 'Unauthorized');
            return null;
        }

        $auth = new AuthContext($this->actorProvider, $this->eventDispatcher);
        $auth->start($token);

        return $this->scope->runScope(new Scope(bindings: [
            AuthContextInterface::class => $auth,
        ]), static fn(): mixed => $handler->handle($context));
    }
}
```

```php
namespace App\Endpoint\Centrifugo;
/**
 * @param Connect $request
 */
public function handle(RequestInterface $request): void
{
    if (!$this->auth->isAuthenticated()) {
        throw new \Exception('Unauthorized', 403);
    }
    
    $request->respond(
        ...
    );
}
```

--------------------------------

### Define route in imported file with RoutingConfigurator

Source: https://github.com/spiral/docs/blob/3.16/docs/en/http/routing.md

Define a route in a separate route file (e.g., web.php) that is imported by the RoutesBootloader. The example adds a route named 'news.show' with pattern '/news/<id:int>', restricts it to GET requests, and maps it to the 'show' action of NewsController. This file is expected to be imported via the import method in the bootloader.

```php
use App\Controller\HomeController;
use Spiral\Router\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes): void {
    $routes->add(name: 'news.show', pattern: '/news/<id:int>')
        ->methods(methods: ['GET'])
        ->action(NewsController::class, 'show');
};
```

--------------------------------

### Using #[BootMethod] with priorities in a bootloader

Source: https://github.com/spiral/docs/blob/3.16/docs/en/framework/bootloaders.md

Use this bootloader to configure routes, middleware, event listeners, and other application-level services during the boot phase. Methods marked with #[BootMethod] run after all initialization completes, support dependency injection, and can be prioritized (higher runs first). The example shows three methods with priorities 10, 0, and -10 to set up error handling, routes, and event listeners in order.

```php
use Spiral\Boot\Attribute\BootMethod;

final class ApplicationBootloader extends Bootloader
{
    // Critical services first
    #[BootMethod(priority: 10)]
    public function configureErrorHandling(ErrorHandler $handler): void
    {
        $handler->addRenderer(new JsonErrorRenderer());
    }
    
    // Standard configuration
    #[BootMethod]
    public function configureRoutes(RouterInterface $router): void
    {
        $router->addRoute('home', new Route('/', HomeController::class));
    }
    
    // Non-critical features last
    #[BootMethod(priority: -10)]
    public function registerEventListeners(
        EventDispatcherInterface $dispatcher
    ): void {
        $dispatcher->addListener(
            ApplicationStarted::class, 
            fn() => $this->onStart()
        );
    }
}
```

--------------------------------

### Set up fake queue and assert pushed job with truth test

Source: https://github.com/spiral/docs/blob/3.16/docs/en/testing/queue.md

Use this test setup to replace the default queue connection with a fake one via `fakeQueue()`. The `FakeQueueManager` and `FakeQueue` instances record pushed jobs, allowing assertions without executing them. The example shows asserting a job with a truth test that checks the handler, queue, and payload.

```php
use Spiral\Mailer\Message;
use Tests\TestCase;

final class UserServiceTest extends TestCase
{
    private \Spiral\Testing\Queue\FakeQueueManager $connection;
    private \Spiral\Testing\Queue\FakeQueue $queue;

    protected function setUp(): void
    {
        parent::setUp();
        $this->connection = $this->fakeQueue();
        $this->queue = $this->connection->getConnection('default');
    }

    public function testUserShouldBeRegistered(): void
    {
        // Perform user registration ...

        $this->queue->assertPushed('mail.job', function (array $data) {
            return $data['handler'] instanceof \Spiral\SendIt\MailJob
                && $data['options']->getQueue() === 'mail'
                && $data['payload']['foo'] === 'bar';
        });
    }
}
```

--------------------------------

### Initialize migrations with migrate:init

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/orm.md

Sets up the migrations tracking table in the database. This command is run automatically when you first run `php app.php migrate`.

```terminal
php app.php migrate:init
```

--------------------------------

### Create a job handler with the scaffolding command

Source: https://github.com/spiral/docs/blob/3.16/docs/en/queue/jobs.md

Use this command to scaffold a new job handler class. It creates a file named SampleJob.php in the app/src/Endpoint/Job directory.

```terminal
php app.php create:jobHandler Sample
```

--------------------------------

### Install spiral/filters-bridge with Composer

Source: https://github.com/spiral/docs/blob/3.16/docs/en/filters/bridge.md

Installation command for the spiral/filters-bridge package. It automatically installs and configures the spiral/validator package, requiring no further configuration.

```terminal
composer require spiral/filters-bridge
```

--------------------------------

### Complete Flow Example: ProductSchema with GridFactory

Source: https://github.com/spiral/docs/blob/3.16/docs/en/data-grid/getting-started.md

Complete flow example showing how to define a schema, handle a controller request, and process a grid with filters, sorting, and pagination. The schema defines filters, a sorter, and a paginator; the controller creates a data source and uses the grid factory to apply user input, returning results with metadata.

```php
// 1. Define Schema
class ProductSchema extends GridSchema 
{
    public function __construct() 
    {
        $this->addFilter('search', new Like('name', new StringValue()));
        $this->addFilter('category', new Equals('category_id', new IntegerValue()));
        $this->addSorter('price', new Sorter('price'));
        $this->setPaginator(new PagePaginator(25));
    }
}

// 2. Controller receives user request
// GET /products?filter[search]=laptop&filter[category]=2&sort[price]=asc&paginate[page]=2&paginate[limit]=25

public function products(
    ProductSchema $schema, 
    GridFactoryInterface $factory, 
    ProductRepository $products
): array {
    // 3. Create base data source
    $select = $products->select(); // Returns Cycle SelectQuery
    
    // 4. Grid Factory processes everything
    $grid = $factory->create($select, $schema);
    
    // What happens inside create():
    // - Input processor extracts: 
    //   filter[search] = "laptop"
    //   filter[category] = "2" 
    //   sort[price] = "asc"
    //   paginate[page] = "2", paginate[limit] = "25"
    //
    // - Schema application:
    //   search filter: Like('name', 'laptop') ✓ valid
    //   category filter: Equals('category_id', 2) ✓ valid (converted to int)
    //   price sorter: Sorter('price', 'asc') ✓ valid
    //   pagination: Limit(25), Offset(25) ✓ valid
    //
    // - Compiler processes with QueryWriter:
    //   $select->where('name', 'LIKE', '%laptop%')
    //          ->where('category_id', 2)  
    //          ->orderBy('price', 'ASC')
    //          ->limit(25)
    //          ->offset(25)
    
    // 5. Return results with metadata
    return [
        'products' => iterator_to_array($grid),                    // Actual product objects
        'total' => $grid->getOption(GridInterface::COUNT),         // Total count for pagination
        'pagination' => $grid->getOption(GridInterface::PAGINATOR), // Current page info
        'filters' => $grid->getOption(GridInterface::FILTERS),     // Applied filters
    ];
}
```

--------------------------------

### Check if session started

Source: https://github.com/spiral/docs/blob/3.16/docs/en/basics/session.md

Checks if the session has started.

```php
dump($this->session->isStarted());
```

--------------------------------

### Using closures for dynamic BootloadConfig

Source: https://github.com/spiral/docs/blob/3.16/docs/en/framework/bootloaders.md

Use a closure to dynamically build BootloadConfig based on container services like AppEnvironment, enabling complex configuration from application state.

```php
use Spiral\Boot\Environment\AppEnvironment;

PrototypeBootloader::class => static fn(AppEnvironment $env) => 
    new BootloadConfig(
        enabled: $env->isLocal(),
        args: ['debug' => $env->get('DEBUG')]
    ),
```

--------------------------------

### BlogPostSchema with best practices

Source: https://github.com/spiral/docs/blob/3.16/docs/en/data-grid/sorters.md

Example schema class demonstrating best practices: user-friendly sorter names, indexed fields, limited complex sorting, sensible defaults, and pre-calculated values for performance.

```php
class BlogPostSchema extends GridSchema
{
    public function __construct()
    {
        // User-friendly sorter names
        $this->addSorter('newest', new DescSorter('published_at'));
        $this->addSorter('oldest', new AscSorter('published_at'));  
        $this->addSorter('popular', new DescSorter('view_count', 'like_count'));
        $this->addSorter('title', new Sorter('title'));
        $this->addSorter('author', new Sorter('author_name'));
        
        // Performance-optimized sorting
        $this->addSorter('trending', new DescSorter('trending_score')); // Pre-calculated
    }
}
```
Tokens:
Raw