The Basics — Prototyping

Spiral comes with a development extension that speeds up the development of application services, controllers, middleware, and other classes via AST modification (a.k.a. it writes code for you). The extension includes IDE friendly tooltips for most common framework components and Cycle Repositories.

#Installation

To install the extension:

composer require spiral/prototype

Make sure to add Spiral\Prototype\Bootloader\PrototypeBootloader to your App class:

protected const APP = [
    //...
    \Spiral\Prototype\Bootloader\PrototypeBootloader::class
];

Note
that the extension will invoke TokenizerConfig, make sure to add it at the end of the bootload chain.

Now you can run php app.php configure to generate IDE tooltips.

#Usage of Prototype Properties

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:

You can use this suggestion directly, without a need for any import:

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')
        ]);
    }
}

Note
that the code will work via magic __get on the object.

Once the prototyping phase is complete, you can remove the trait and inject dependencies via:

php app.php prototype:inject -r

Note
Use -r flag to remove PrototypeTrait.

The extension will modify your class into the given form:

namespace App\Endpoint\Web;

use App\Database\Repository\UserRepository;
use Spiral\Views\ViewsInterface;

class HomeController
{
    public function __construct(
        private readonly ViewsInterface $views, 
        private readonly UserRepository $users
    ) {
    }

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

Note
that the formatting around the injected lines will be affected.

For PHP 7.4 there are two additional flags available now:

• typedProperties (t) will inject properties with a type
• no-phpdoc will omit PHP doc block for typed properties

Note
that these flags work only if the latest nikic/php-parser version with PHP 7.4 support is installed.

php app.php prototype:inject -r -t --no-phpdoc

namespace App\Endpoint\Web;

use App\Database\Repository\UserRepository;
use Spiral\Views\ViewsInterface;

class HomeController
{
    public function __construct(
        private readonly ViewsInterface $views, 
        private readonly UserRepository $users
    ) {
    }

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

To view all the classes which use prototyped properties without modifying them:

php app.php prototype:list

Note
that you can remove the spiral/prototype extension after all the injects are complete.

#Custom Properties

You can register any number of prototyped properties using Spiral\Prototype\Bootloader\PrototypeBootloader in your bootloader:

use Spiral\Prototype\Bootloader\PrototypeBootloader;

public function boot(PrototypeBootloader $prototype): void
{
    $prototype->bindProperty('myService', MyService::class);
}

Note
that you can combine such an approach with automatic class discovery to achieve better integration of domain layer architecture into your development process.

#Attribute Based

Alternatively, you can use attributes to register prototype classes and services. Use attribute Spiral\Prototype\Annotation\Prototyped in the class you want to inject:

namespace App\Domain\User\Service;

use Spiral\Prototype\Annotation\Prototyped;

#[Prototyped(property: 'userService')]
final class UserService
{
    // ...
}

Make sure to run php app.php update or php app.php prototype:dump to auto-locate your service.

#Available Shortcuts

There are a number of component shortcuts available for you to use: