Spiral Framework Versions Save

High-Performance PHP Framework

3.12.0

2 months ago

What's Changed

New features

1. Improved container injectors

spiral/core Advanced Context Handling in Injector Implementations by @roxblnfk in https://github.com/spiral/framework/pull/1041

This pull request presents a significant update to the injector system, focusing on the createInjection method of the Spiral\Core\Container\InjectorInterface. The key enhancement lies in the augmented ability of the injector to handle context more effectively.

Previously, the createInjection method accepted two parameters: the ReflectionClass object of the requested class and a context, which was limited to being either a string or null. This approach, while functional, offered limited flexibility in dynamically resolving dependencies based on the calling context.

The updated createInjection method can now accept an extended range of context types including Stringable|string|null, mixed, or ReflectionParameter|string|null. This broadening allows the injector to receive more detailed contextual information, enhancing its capability to make more informed decisions about which implementation to provide.

Now you can do something like this:

<?php

declare(strict_types=1);

namespace App\Application;

final class SomeService
{
    public function __construct(
        #[DatabaseDriver(name: 'mysql')]
        public DatabaseInterface $database,

        #[DatabaseDriver(name: 'sqlite')]
        public DatabaseInterface $database1,
    ) {
    }
}

And example of injector

<?php

declare(strict_types=1);

namespace App\Application;

use Spiral\Core\Container\InjectorInterface;

final class DatabaseInjector implements InjectorInterface
{
    public function createInjection(\ReflectionClass $class, \ReflectionParameter|null|string $context = null): object
    {
        $driver = $context?->getAttributes(DatabaseDriver::class)[0]?->newInstance()?->name ?? 'mysql';

        return match ($driver) {
            'sqlite' => new Sqlite(),
            'mysql' => new Mysql(),
            default => throw new \InvalidArgumentException('Invalid database driver'),
        };
    }
}

2. Added ability to suppress non-reportable exceptions

Add non-reportable exceptions by @msmakouz in https://github.com/spiral/framework/pull/1044

The ability to exclude reporting of certain exceptions has been added. By default, Spiral\Http\Exception\ClientException, Spiral\Filters\Exception\ValidationException, and Spiral\Filters\Exception\AuthorizationException are ignored.

Exceptions can be excluded from the report in several different ways:

Attribute NonReportable

To exclude an exception from the report, you need to add the Spiral\Exceptions\Attribute\NonReportable attribute to the exception class.

use Spiral\Exceptions\Attribute\NonReportable;

#[NonReportable]
class AccessDeniedException extends \Exception
{
    // ...
}

Method dontReport

Invoke the dontReport method in the Spiral\Exceptions\ExceptionHandler class. This can be done using the bootloader.

use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Exceptions\ExceptionHandler;

final class AppBootloader extends Bootloader
{
    public function init(ExceptionHandler $handler): void
    {
        $handler->dontReport(EntityNotFoundException::class);
    }
}

Overriding the property nonReportableExceptions

You can override the nonReportableExceptions property with predefined exceptions.

3. Better container scopes

This release marks a foundational shift in how we approach dependency management within our framework, setting the stage for the upcoming version 4.0. With these changes, we're not just tweaking the system; we're laying down the groundwork for more robust, efficient, and intuitive handling of dependencies in the long run. To ensure everyone can make the most out of these updates, we will be rolling out a series of tutorials aimed at helping you navigate through the new features and enhancements.

Context

The context is also extended on other container methods get() (see https://github.com/spiral/framework/pull/1041)

Scopes

Default scope fix

If the container scope is not open, it is assumed by default that dependencies are resolved in the scope named root. Now when calling invoke(), make(), get(), the container will globally register itself with the root scope if no other scope was opened. Before this, the container resolved dependencies as if outside the scope.

Scoped Interface

The experimental ContainerScopeInterface has been removed. The method getBinder(?string $scope = null): BinderInterface has been moved to BinderInterface at the annotation level.

runScope method

The Container::runScoped() method (in the implementation) was additionally marked as @deprecated and will be removed when its use in tests is reduced to zero. Instead of the Container::runScoped(), you should now call the old Container::runScope(), but with passing the DTO Spiral\Core\Scope instead of the list of bindings.

$container->runScope(
    new Scope(name: 'auth', bindings: ['actor' => new Actor()]),
    function(ContainerInterface $container) {
        dump($container->get('actor'));
    },
);

Scope Proxy

Instead of the now removed ContainerScopeInterface::getCurrentContainer() method, the user is offered another way to get dependencies from the container of the current scope - a proxy.

The user can mark the dependency with a new attribute Spiral\Core\Attribute\Proxy.

Warning: The dependency must be defined by an interface.

When resolving dependencies, the container will create a proxy object that implements the specified interface. When calling the interface method, the proxy object will get the container of the current scope, request the dependency from it using its interface, and start the necessary method.

final class Service  
{
    public function __construct(  
        #[Proxy] public LoggerInterface $logger,  
    ) {  
    }

    public function doAction() {
        // Equals to
        // $container->getCurrentContainer()->get(LoggerInterface::class)->log('foo')
        $this->logger->log('foo'); 
    }
}

Important nuances:

  • The proxy refers to the active scope of the container, regardless of the scope in which the proxy object was created.
  • Each call to the proxy method pulls the container. If there are many calls within the method, you should consider making a proxy for the container 
    // class
function __construct(
    #[Proxy] private Dependency $dep,
    #[Proxy] private ContainerInterface $container,
) {}
function handle() {
    // There are four calls to the container under the hood.
    $this->dep->foo();
    $this->dep->bar();
    $this->dep->baz();
    $this->dep->red();

    // Only two calls to the container and caching the value in a variable
    // The first call - getting the container through the proxy
    // The second - explicit retrieval of the dependency from the container
    $dep = $this->container->get(Dependency::class);
    $dep->foo();
    $dep->bar();
    $dep->baz();
    $dep->red();
}
  • The proxied interface should not contain a constructor signature (although this sometimes happens).
  • Calls to methods outside the interface will not be proxied. This option is possible in principle, but it is disabled. If it is absolutely necessary, we will consider whether to enable it.
  • The destructor method call will not be proxied.

Proxy

Added the ability to bind an interface as a proxy using the Spiral\Core\Config\Proxy configuration. This is useful in cases where a service needs to be used within a specific scope but must be accessible within the container for other services in root or other scopes (so that a service requiring the dependency can be successfully created and used when needed in the correct scope).

use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Core\BinderInterface;
use Spiral\Core\Config\Proxy;
use Spiral\Framework\ScopeName;
use Spiral\Http\PaginationFactory;
use Spiral\Pagination\PaginationProviderInterface;

final class PaginationBootloader extends Bootloader
{
    public function __construct(
        private readonly BinderInterface $binder,
    ) {
    }
    
    public function defineSingletons(): array
    {
        $this->binder
            ->getBinder(ScopeName::Http)
            ->bindSingleton(PaginationProviderInterface::class, PaginationFactory::class);
        
        $this->binder->bind(
            PaginationProviderInterface::class,
            new Proxy(PaginationProviderInterface::class, true)  // <-------
        );

        return [];
    }
}

DeprecationProxy

Similar to Proxy, but also allows outputting a deprecation message when attempting to retrieve a dependency from the container. In the example below, we use two bindings, one in scope and one out of scope with Spiral\Core\Config\DeprecationProxy. When requesting the interface in scope, we will receive the service, and when requesting it out of scope, we will receive the service and a deprecation message.

use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Core\BinderInterface;
use Spiral\Core\Config\DeprecationProxy;
use Spiral\Framework\ScopeName;
use Spiral\Http\PaginationFactory;
use Spiral\Pagination\PaginationProviderInterface;

final class PaginationBootloader extends Bootloader
{
    public function __construct(
        private readonly BinderInterface $binder,
    ) {
    }

    public function defineSingletons(): array
    {
        $this->binder
            ->getBinder(ScopeName::Http)
            ->bindSingleton(PaginationProviderInterface::class, PaginationFactory::class);

        $this->binder->bind(
            PaginationProviderInterface::class,
            new DeprecationProxy(PaginationProviderInterface::class, true, ScopeName::Http, '4.0') // <----------
        );

        return [];
    }
}

DispatcherScope

Added the ability to specify the scope name for the dispatcher using the Spiral\Attribute\DispatcherScope attribute.

use Spiral\Attribute\DispatcherScope;
use Spiral\Boot\DispatcherInterface;

#[DispatcherScope(scope: 'console')]
final class ConsoleDispatcher implements DispatcherInterface
{
    // ...
}
Registration of dispatchers

The registration of dispatchers has been changed. The accepted type in the addDispatcher method of the Spiral\Boot\AbstractKernel class has been extended from DispatcherInterface to string|DispatcherInterface. Before these changes, the method accepted a created DispatcherInterface object, now it can accept a class name string or an object. In version 4.0, the DispatcherInterface type will be removed. When passing an object, only its class name will be saved. And when using the dispatcher, its object will be created anew.

Example with ConsoleDispatcher:

public function init(AbstractKernel $kernel): void
{
    $kernel->bootstrapped(static function (AbstractKernel $kernel): void {
        $kernel->addDispatcher(ConsoleDispatcher::class);
    });
}
Using dispatchers

The dispatchers are now created in their own scope and receive dependencies that are specified in this scope. But due to the need to check whether the dispatcher can handle the request or not before creating the dispatcher object, the canServe method in dispatchers must be static:

public static function canServe(EnvironmentInterface $env): bool
{
    return (PHP_SAPI === 'cli' && $env->get('RR_MODE') === null);
}

This method has been removed from the Spiral\Boot\DispatcherInterface, for backward compatibility it can be non-static, as it was before (then an object will be created for its call) or static and accept Spiral\Boot\EnvironmentInterface.

4. Added scaffolder:info console command

Adds scaffolder:info console command by @butschster in https://github.com/spiral/framework/pull/1068

Now you can list available commands.

image

Other

New Contributors

Full Changelog: https://github.com/spiral/framework/compare/3.11.1...3.12.0

3.11.1

4 months ago

What's Changed

Full Changelog: https://github.com/spiral/framework/compare/3.11.0...3.11.1

3.11.0

4 months ago

What's Changed

Other changes

Bugfixes

Full Changelog: https://github.com/spiral/framework/compare/3.10.1...3.11.0

3.10.1

5 months ago

What's Changed

Full Changelog: https://github.com/spiral/framework/compare/3.10.0...3.10.1

3.10.0

5 months ago

Improvements

1. Improved the bootloader registration process

We've introduced a new interface, Spiral\Boot\Bootloader\BootloaderRegistryInterface, and its implementation, Spiral\Boot\Bootloader\BootloaderRegistry. This update makes the process of registering bootloaders in Spiral much simpler and more flexible.

Now, you can easily manage your bootloaders using our spiral-packages/discoverer package. This package helps you automatically find and register bootloaders specified in your composer.json like in example below:

{
  // ...
  "extra": {
    "spiral": {
      "bootloaders": [
        "Spiral\\Monolog\\Bootloader\\DotenvBootloader",
        "Spiral\\DotEnv\\Bootloader\\MonologBootloader"
      ],
      "dont-discover": [
        "spiral-packages/event-bus"
      ]
    }
  }
}

This feature also allows for bootloader discovery from various sources, such as configuration files or other custom methods.

by @msmakouz in https://github.com/spiral/framework/pull/1015

2. Enhanced Error Handling for Incorrect Data Types in Filters.

The spiral/filters package in Spiral's ecosystem is designed for filtering and, optionally, validating input data. It enables you to set specific rules for each input field, ensuring that the data received matches the expected format and other defined criteria.

For example, consider this filter:

namespace App\Endpoint\Web\Filter;

use Spiral\Filters\Attribute\Input\Query;
use Spiral\Filters\Model\Filter;

final class UserFilter extends Filter
{
    #[Query(key: 'username')]
    public string $username;
}

In this scenario, the username is expected to be a string. However, there might be instances where the input data is of the wrong type, such as an array or an integer. Previously, such mismatches would result in an exception being thrown by the application.

With the new update, we've added the capability to specify custom error messages for these mismatches. This enhancement allows for more graceful handling of incorrect data types. Here's how you can implement it:

namespace App\Endpoint\Web\Filter;

use Spiral\Filters\Attribute\Input\Query;
use Spiral\Filters\Model\Filter;
use Spiral\Filters\Attribute\CastingErrorMessage;

final class UserFilter extends Filter
{
    #[Query(key: 'username')]
    #[CastingErrorMessage('Invalid type')]
    public string $username;
}

This update ensures that your application can provide clearer feedback when encountering data of an unexpected type.

by @msmakouz in https://github.com/spiral/framework/pull/1016

3. Added the ability to configure bootloaders via BootloadConfig

There is a new DTO class Spiral\Boot\Attribute\BootloadConfig which enables the inclusion or exclusion of bootloaders, passing parameters that will be forwarded to the init and boot methods of the bootloader, and dynamically adjusting the bootloader loading based on environment variables.

Here is a simple example:

namespace App\Application;

use Spiral\Boot\Attribute\BootloadConfig;
use Spiral\Prototype\Bootloader\PrototypeBootloader;

class Kernel extends \Spiral\Framework\Kernel
{
    // ...
    public function defineBootloaders(): array
    {
        return [
            // ...
            PrototypeBootloader::class => new BootloadConfig(allowEnv: ['APP_ENV' => ['local', 'dev']]),
            // ...
        ];
    }
    
    // ...
}

In this example, we specified that the PrototypeBootloader should be loaded only if the environment variable APP_ENV is defined and has a value of local or dev.

You can also define a function that returns a BootloadConfig object. This function can take arguments, which might be obtained from the container.

PrototypeBootloader::class => static fn (AppEnvironment $env) => new BootloadConfig(enabled: $env->isLocal()),

You can also use BootloadConfig class as an attribute to control how a bootloader behaves.

use Spiral\Boot\Attribute\BootloadConfig;
use Spiral\Boot\Bootloader\Bootloader;

#[BootloadConfig(allowEnv: ['APP_ENV' => 'local'])]
final class SomeBootloader extends Bootloader
{
}

Attributes are a great choice when you want to keep the configuration close to the bootloader's code. It's a more intuitive way to set up bootloaders, especially in cases where the configuration is straightforward and doesn't require complex logic.

By extending BootloadConfig, you can create custom classes that encapsulate specific conditions under which bootloaders should operate.

Here's an example

class TargetRRWorker extends BootloadConfig {
    public function __construct(array $modes)
    {
        parent::__construct(
            env: ['RR_MODE' => $modes],
        );
    }
}

// ...

class Kernel extends Kernel
{
    public function defineBootloaders(): array
    {
        return [
            HttpBootloader::class => new TargetRRWorker(['http']),
            RoutesBootloader::class => new TargetRRWorker(['http']),
            // Other bootloaders...
        ];
    }
}

by @msmakouz in https://github.com/spiral/framework/pull/1017

Other changes

Bugfixes

Full Changelog: https://github.com/spiral/framework/compare/3.9.1...3.10

3.9.0

6 months ago

Improvements

1. Added RetryPolicyInterceptor for Queue component

Added Spiral\Queue\Interceptor\Consume\RetryPolicyInterceptor to enable automatic job retries with a configurable retry policy. To use it, need to add the Spiral\Queue\Attribute\RetryPolicy attribute to the job class:

use Spiral\Queue\Attribute\RetryPolicy;
use Spiral\Queue\JobHandler;

#[RetryPolicy(maxAttempts: 3, delay: 5, multiplier: 2)]
final class Ping extends JobHandler
{
    public function invoke(array $payload): void
    {
        // ...
    }
}

Create an exception that implements interface Spiral\Queue\Exception\RetryableExceptionInterface:

use Spiral\Queue\Exception\RetryableExceptionInterface;
use Spiral\Queue\RetryPolicyInterface;

class RetryException extends \DomainException implements RetryableExceptionInterface
{
    public function isRetryable(): bool
    {
        return true;
    }

    public function getRetryPolicy(): ?RetryPolicyInterface
    {
        return null;
    }
}

The exception must implement the two methods isRetryable and getRetryPolicy. These methods can override the retry behavior and cancel the re-queue- or change the retry policy.

If a RetryException is thrown while a job runs, the job will be re-queued according to the retry policy.

Pull request: https://github.com/spiral/framework/pull/980 by @msmakouz

2. Added the ability to configure serializer and job type for Queue component via attributes

Added ability to configure serializer and job type using attributes.

use App\Domain\User\Entity\User;
use Spiral\Queue\Attribute\Serializer;
use Spiral\Queue\Attribute\JobHandler as Handler;
use Spiral\Queue\JobHandler;

#[Handler('ping')]
#[Serializer('marshaller-json')]
final class Ping extends JobHandler
{
    public function invoke(User $payload): void
    {
        // ...
    }
}

Pull request: https://github.com/spiral/framework/pull/990 by @msmakouz

3. Added the ability to configure the Monolog messages format

Now you can configure the Monolog messages format via environment variable MONOLOG_FORMAT.

MONOLOG_FORMAT="[%datetime%] %level_name%: %message% %context%\n"

Pull request: https://github.com/spiral/framework/pull/994 by @msmakouz

4. Added the ability to register additional translation directories

Now you can register additional directories with translation files for the Translator component. This can be useful when developing additional packages for the Spiral Framework, where the package may provide translation files (for example, validators). Translation files in an application can override translations from additional directories.

A directory with translations can be registered via the Spiral\Bootloader\I18nBootloader bootloader or translator.php configuration file.

Via I18nBootloader bootloader

use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Bootloader\I18nBootloader;

final class AppBootloader extends Bootloader
{
    public function init(I18nBootloader $i18n): void
    {
        $i18n->addDirectory('some/directory');
    }
}

Via configuration file

return [
    // ...
    'directories' => [
        'some/directory'
    ],
    // ...
];

Pull request: https://github.com/spiral/framework/pull/996 by @msmakouz

5. Added the ability to store snapshots using Storage component

Have you ever faced challenges in storing your app's exception snapshots when working with stateless applications? We've got some good news. With our latest update, we've made it super easy for you.

By integrating with the spiral/storage component, we're giving your stateless apps the power to save exception snapshots straight into S3.

Why is this awesome for you?

  1. Simplified Storage: No more juggling with complex storage solutions. Save snapshots directly to S3 with ease.
  2. Tailored for Stateless Apps: Designed specifically for stateless applications, making your deployments smoother and hassle-free.
  3. Reliability: With S3's proven track record, know your snapshots are stored safely and can be accessed whenever you need.

How to use:

  1. Switch to the new bootloader: Swap out Spiral\Bootloader\SnapshotsBootloader with Spiral\Bootloader\StorageSnapshotsBootloader.
  2. Set up your bucket for snapshot storage and specify the desired bucket using the SNAPSHOTS_BUCKET environment variable.
  3. Modify app/src/Application/Bootloader/ExceptionHandlerBootloader.php to replace the exception reporter Spiral\Exceptions\Reporter\FileReporter with Spiral\Exceptions\Reporter\StorageReporter in the boot method (an example for a default installation of spiral/app).

Pull request: https://github.com/spiral/framework/pull/986 by @msmakouz

6. Introduced new prototype:list console command for listing prototype dependencies

The prototype:list command is a super cool addition to our Spiral Framework. It helps developers by providing an easy way to list all the classes registered in the Spiral\Prototype\PrototypeRegistry. These registered classes are essential for project prototyping.

How to Use It

Using the command is simple. Just run the following line in your terminal:

php app.php prototype:list

Once you do that, you'll get a neat table that displays all the registered prototypes, including their names and target classes. This makes it incredibly easy to see what's available for your project prototyping needs.

+------------------+-------------------------------------------------------+
| Name:            | Target:                                               |
+------------------+-------------------------------------------------------+
| app              | App\Application\Kernel                                |
| classLocator     | Spiral\Tokenizer\ClassesInterface                     |
| console          | Spiral\Console\Console                                |
| broadcast        | Spiral\Broadcasting\BroadcastInterface                |
| container        | Psr\Container\ContainerInterface                      |
| encrypter        | Spiral\Encrypter\EncrypterInterface                   |
| env              | Spiral\Boot\EnvironmentInterface                      |
| files            | Spiral\Files\FilesInterface                           |
| guard            | Spiral\Security\GuardInterface                        |
| http             | Spiral\Http\Http                                      |
| i18n             | Spiral\Translator\TranslatorInterface                 |
| input            | Spiral\Http\Request\InputManager                      |
| session          | Spiral\Session\SessionScope                           |
| cookies          | Spiral\Cookies\CookieManager                          |
| logger           | Psr\Log\LoggerInterface                               |
| logs             | Spiral\Logger\LogsInterface                           |
| memory           | Spiral\Boot\MemoryInterface                           |
| paginators       | Spiral\Pagination\PaginationProviderInterface         |
| queue            | Spiral\Queue\QueueInterface                           |
| queueManager     | Spiral\Queue\QueueConnectionProviderInterface         |
| request          | Spiral\Http\Request\InputManager                      |
| response         | Spiral\Http\ResponseWrapper                           |
| router           | Spiral\Router\RouterInterface                         |
| snapshots        | Spiral\Snapshots\SnapshotterInterface                 |
| storage          | Spiral\Storage\BucketInterface                        |
| serializer       | Spiral\Serializer\SerializerManager                   |
| validator        | Spiral\Validation\ValidationInterface                 |
| views            | Spiral\Views\ViewsInterface                           |
| auth             | Spiral\Auth\AuthScope                                 |
| authTokens       | Spiral\Auth\TokenStorageInterface                     |
| cache            | Psr\SimpleCache\CacheInterface                        |
| cacheManager     | Spiral\Cache\CacheStorageProviderInterface            |
| exceptionHandler | Spiral\Exceptions\ExceptionHandlerInterface           |
| users            | App\Infrastructure\Persistence\CycleORMUserRepository |
+------------------+-------------------------------------------------------+

Why It Matters

This new feature enhances developer productivity and ensures that we're making the most of the Spiral Framework's capabilities. It provides clarity on available prototypes, which can be crucial when building and extending our projects.

Note You might notice that we've also renamed the old prototype:list command to prototype:usage to better align with its purpose.

Pull request: https://github.com/spiral/framework/pull/1003 by @msmakouz

Other changes

  1. [spiral/scaffolder] Changed Queue job handler payload type from array to mixed by @msmakouz in https://github.com/spiral/framework/pull/992
  2. [spiral/monolog-bridge] Set bubble as true by default in logRotate method by @msmakouz in https://github.com/spiral/framework/pull/997
  3. [spiral/prototype] Initialize PrototypeRegistry only when registry requires from container by @msmakouz in https://github.com/spiral/framework/pull/1005

Bug fixes

  1. [spiral/router] Fixed issue with Registering Routes Containing Host using RoutesBootloader by @msmakouz in https://github.com/spiral/framework/pull/990
  2. [spiral/reactor] Fix Psalm issues and tests in Reactor by @msmakouz in https://github.com/spiral/framework/pull/1002

Full Changelog: https://github.com/spiral/framework/compare/3.8.4...3.9.0

3.8.4

8 months ago

What's Changed

Full Changelog: https://github.com/spiral/framework/compare/3.8.3...3.8.4

3.8.3

8 months ago

What's Changed

Full Changelog: https://github.com/spiral/framework/compare/3.8.2...3.8.3

3.8.2

8 months ago

What's Changed

Full Changelog: https://github.com/spiral/framework/compare/3.8.1...3.8.2

3.8.1

8 months ago

What's Changed

Full Changelog: https://github.com/spiral/framework/compare/3.8.0...3.8.1