Skip to content

v3.5.0

Latest

Choose a tag to compare

@GautierDele GautierDele released this 14 Nov 09:27
276517c

A minor release of 3.x: instructions declared by their class. Upgrade with composer update lomkit/laravel-rest-api, then read the 3.5 section of the upgrade guide.

Instructions declared by their class

  • instructions() accepts class names next to instances, and an instruction can inject the services it needs:

    public function instructions(): array
    {
        return [
            HeldByInstruction::class,
            UpcomingDeadlinesInstruction::class,
            UnendedInstruction::make()->meta(['group' => 'dates']),
        ];
    }
    
    class UpcomingDeadlinesInstruction extends Instruction
    {
        public ?string $name = 'Upcoming deadlines';
    
        public function __construct(private readonly DeadlineCalendar $calendar) {}
    }
  • The container builds the listed classes the first time the resource reads its instructions in a request: a search that sends instructions (at its root, in an include of the resource, or in the search of an action or a metric), or /details. A request that reads no instruction, such as a mutation or a search without instructions, builds none, and registering the routes reads no instruction.

  • Reading one instruction builds the whole list of the resource: keep the constructors light and do the work in handle().

  • Each class is built once per resource definition, that is once per request. The OpenAPI document and rest:check build their own.

  • Instructions have no route, so an instruction listed by its class can still override name() or uriKey().

  • A name that is not a class extending Instruction, Instruction::class itself, an abstract class, or a container binding that returns another class throws InvalidInstructionException when the instructions are read, with a message that names the resource.

  • php artisan rest:check builds every instruction of the resources of the checked controllers and of every resource their relations reach, since an include can read them. It reports these errors, a constructor parameter that the container cannot resolve and any other constructor error in its declarations section, each with the name of the resource.

  • /details, the OpenAPI document and searches stay the same for a class and the matching instance. Instances still work, for an instruction built with arguments or reused with other settings, and one list can mix both forms.

  • rest:instruction prints the class form to list in the resource.

Check after upgrading

  • Move the settings of an instruction into its properties and list it by its class; keep the instance form for one built with arguments or reused with other settings. Then run php artisan rest:check.
  • rest:check counts the instructions it builds: 4 actions, 2 metrics, 3 instructions built, and "instructions" in the declarations key of --json.

Documentation: https://laravel-rest-api.lomkit.com