Callbacks and CallbackAnnotationTasks

This is a separate annotations tool that focuses on methods and their doc blocks instead of classes. By default it ships with:

• TableCallbackAnnotatorTask

Table Callback Annotations

Behaviors and generic code use the following signature:

/**
 * @param \Cake\Event\EventInterface $event Event
 * @param \Cake\Datasource\EntityInterface $entity Entity
 * @param \ArrayObject $options Options
 * @return void
 */
public function beforeSave(EventInterface $event, EntityInterface $entity, ArrayObject $options): void {
}

As long as you only use methods and attributes of the EntityInterface contract, this is fine.

But in specific Table-class code, you usually also access the entity's concrete properties. There the type hint is somewhat a lie. To please the IDE and tooling like PHPStan we can at least fix up the doc block. That is what this task does, declaring the Post entity to be available and used inside.

Inside the concrete PostsTable after running the callbacks command:

/**
 * @param \Cake\Event\EventInterface $event Event
 * @param \App\Model\Entity\Post $entity Entity
 * @param \ArrayObject $options Options
 * @return void
 */
public function beforeSave(EventInterface $event, EntityInterface $entity, ArrayObject $options): void {
}

Entity Virtual Field Setter/Getter Annotations

A virtual field will be "linked" to the property it handles:

/**
 * @see \App\Model\Entity\MyEntity::$expected_type
 *
 * @return int|null
 */
protected function _getExpectedType(): ?int {
    return null;
}

This way you can quick-jump from the property to the getter and vice versa within your IDE.

Custom Tasks

Create your own task class:

namespace App\Annotator\CallbackAnnotatorTask;

use IdeHelper\Annotator\CallbackAnnotatorTask\AbstractCallbackAnnotatorTask;
use IdeHelper\Annotator\CallbackAnnotatorTask\CallbackAnnotatorTaskInterface;

class MyCallbackAnnotatorTask extends AbstractCallbackAnnotatorTask implements CallbackAnnotatorTaskInterface {

    /**
     * @param string $path
     * @return bool
     */
    public function shouldRun(string $path): bool {
        // Implement the task-specific condition or update here.
        return false;
    }

    /**
     * @param string $path
     * @return bool
     */
    public function annotate(string $path): bool {
        // Implement the task-specific condition or update here.
        return false;
    }

}

Then add it to the config:

'IdeHelper' => [
    'callbackAnnotatorTasks' => [
        'MyCallbackAnnotatorTask' => \App\Annotator\CallbackAnnotatorTask\MyCallbackAnnotatorTask::class,
    ],
],

The key 'MyCallbackAnnotatorTask' can be any string.

Replacing existing tasks works the same way as for classes: use the native class name as key, your replacement as value, or null to disable.