nystudio107 / craft-twigfield

src/services/AutocompleteService.php

<?php
/**
 * Twigfield for Craft CMS
 *
 * Provides a twig editor field with Twig & Craft API autocomplete
 *
 * @link      https://nystudio107.com

The tag in position 1 should be the @copyright tag

 * @copyright Copyright (c) 2022 nystudio107

@copyright tag must contain a year and the name of the copyright holder

 */

PHP version not specified

Missing @category tag in file comment

Missing @package tag in file comment

Missing @author tag in file comment

Missing @license tag in file comment

namespace nystudio107\twigfield\services;

use Craft;
use craft\base\Component;
use craft\events\SectionEvent;
use craft\services\Fields;
use nystudio107\twigfield\autocompletes\SectionShorthandFieldsAutocomplete;
use nystudio107\twigfield\base\Autocomplete as BaseAutoComplete;
use nystudio107\twigfield\base\AutocompleteInterface;
use nystudio107\twigfield\events\RegisterTwigfieldAutocompletesEvent;
use nystudio107\twigfield\Twigfield;
use yii\base\Event;
use yii\caching\TagDependency;

/**
 * Class Autocomplete
 *
 * @author    nystudio107

The tag in position 1 should be the @package tag

Content of the @author tag must be in the form "Display Name <username@example.com>"

Tag value for @author tag indented incorrectly; expected 2 spaces but found 4

 * @package   Twigfield

Tag value for @package tag indented incorrectly; expected 1 spaces but found 3

 * @since     1.0.0

The tag in position 3 should be the @author tag

Tag value for @since tag indented incorrectly; expected 3 spaces but found 5

 */

Missing @category tag in class comment

Missing @license tag in class comment

Missing @link tag in class comment

class AutocompleteService extends Component
{
    // Constants
    // =========================================================================

    /**

Missing short description in doc comment

     * @event RegisterTwigfieldAutocompletesEvent The event that is triggered when registering
     *        Twigfield Autocomplete types
     *
     * Autocomplete Generator types must implement [[AutocompleteInterface]]. [[AutoComplete]]
     * provides a base implementation.
     *
     * ```php
     * use nystudio107\twigfield\services\AutocompleteService;
     * use nystudio107\twigfield\events\RegisterTwigfieldAutocompletesEvent;
     * use yii\base\Event;
     *
     * Event::on(AutocompleteService::class,
     *     AutocompleteService::EVENT_REGISTER_TWIGFIELD_AUTOCOMPLETES,
     *     function(RegisterTwigfieldAutocompletesEvent $event) {
     *         $event->types[] = MyAutocomplete::class;
     *     }
     * );
     *
     * or to pass in a config array for the Autocomplete object:
     *
     * Event::on(AutocompleteService::class,
     *     AutocompleteService::EVENT_REGISTER_TWIGFIELD_AUTOCOMPLETES,
     *     function(RegisterTwigfieldAutocompletesEvent $event) {
     *         $config = [
     *             'property' => value,
     *         ];
     *         $event->types[] = [MyAutocomplete::class => $config];
     *     }
     * );
     *
     * ```
     */
    const EVENT_REGISTER_TWIGFIELD_AUTOCOMPLETES = 'registerTwigfieldAutocompletes';

    const AUTOCOMPLETE_CACHE_TAG = 'TwigFieldAutocompleteTag';

    // Public Properties
    // =========================================================================

    /**

Missing short description in doc comment

     * @var string Prefix for the cache key
     */
    public $cacheKeyPrefix = 'TwigFieldAutocomplete';

    /**

Missing short description in doc comment

     * @var int Cache duration
     */
    public $cacheDuration = 3600;

    // Public Methods
    // =========================================================================

    /**

Missing short description in doc comment

     * @inerhitDoc
     */

Missing @return tag in function comment

    public function init(): void
    {
        parent::init();
        // Short cacheDuration if we're in devMode
        if (Craft::$app->getConfig()->getGeneral()->devMode) {
            $this->cacheDuration = 1;
        }
        // Invalidate any SectionShorthandFieldsAutocomplete caches whenever any field layout is edited
        Event::on(Fields::class, Fields::EVENT_AFTER_SAVE_FIELD_LAYOUT, function (SectionEvent $e) {

The parameter $e is not used and could be removed.

The opening parenthesis of a multi-line function call should be the last content on the line.

            $this->clearAutocompleteCache(SectionShorthandFieldsAutocomplete::class);
        });

For multi-line function calls, the closing parenthesis should be on a new line.

    }

    /**
     * Call each of the autocompletes to generate their complete items
     * @param string $fieldType

There must be exactly one blank line before the tags in a doc comment

Missing parameter comment

Tag value for @param tag indented incorrectly; expected 2 spaces but found 1

     * @param array $twigfieldOptions

Expected 2 spaces after parameter type; 1 found

Missing parameter comment

Tag value for @param tag indented incorrectly; expected 2 spaces but found 1

     * @return array

Tag @return cannot be grouped with parameter tags in a doc comment

     */
    public function generateAutocompletes(string $fieldType = Twigfield::DEFAULT_FIELD_TYPE, array $twigfieldOptions = []): array
    {
        $autocompleteItems = [];
        $autocompletes = $this->getAllAutocompleteGenerators($fieldType);
        foreach ($autocompletes as $autocompleteGenerator) {
            /* @var BaseAutoComplete $autocomplete */
            // Assume the generator is a class name string
            $config = [
                'fieldType' => $fieldType,
                'twigfieldOptions' => $twigfieldOptions,
            ];
            $autocompleteClass = $autocompleteGenerator;
            // If we're passed in an array instead, extract the class name and config from the key/value pair
            // in the form of [className => configArray]
            if (is_array($autocompleteGenerator)) {
                $autocompleteClass = array_key_first($autocompleteGenerator);
                /** @noinspection SlowArrayOperationsInLoopInspection */

The open comment tag must be the only content on the line

Missing short description in doc comment

The close comment tag must be the only content on the line

                $config = array_merge($config, $autocompleteGenerator[$autocompleteClass]);
            }
            $autocomplete = new $autocompleteClass($config);
            $name = $autocomplete->name;
            // Set up the cache parameters
            $cache = Craft::$app->getCache();
            $cacheKey = $this->getAutocompleteCacheKey($autocomplete, $config);
            $dependency = new TagDependency([

The opening parenthesis of a multi-line function call should be the last content on the line.

                'tags' => [
                    self::AUTOCOMPLETE_CACHE_TAG,
                    self::AUTOCOMPLETE_CACHE_TAG . $name,
                    self::AUTOCOMPLETE_CACHE_TAG . get_class($autocomplete),
                ],
            ]);

For multi-line function calls, the closing parenthesis should be on a new line.

            // Get the autocompletes from the cache, or generate them if they aren't cached
            $autocompleteItems[$name] = $cache->getOrSet($cacheKey, static function () use ($name, $autocomplete) {

The opening parenthesis of a multi-line function call should be the last content on the line.

                $autocomplete->generateCompleteItems();
                return [
                    'name' => $name,
                    'type' => $autocomplete->type,
                    'hasSubProperties' => $autocomplete->hasSubProperties,
                    BaseAutoComplete::COMPLETION_KEY => $autocomplete->getCompleteItems(),
                ];
            }, $this->cacheDuration, $dependency);

For multi-line function calls, the closing parenthesis should be on a new line.

        }
        Craft::info('Twigfield Autocompletes generated', __METHOD__);

        return $autocompleteItems;
    }

    /**
     * Clear the specified autocomplete cache (or all autocomplete caches if left empty)
     *
     * @param string $autocompleteName

Missing parameter comment

Tag value for @param tag indented incorrectly; expected 2 spaces but found 1

     * @return void

Tag @return cannot be grouped with parameter tags in a doc comment

     */
    public function clearAutocompleteCache(string $autocompleteName = ''): void
    {
        $cache = Craft::$app->getCache();
        TagDependency::invalidate($cache, self::AUTOCOMPLETE_CACHE_TAG . $autocompleteName);
        Craft::info('Twigfield caches invalidated', __METHOD__);
    }

    /**
     * Return the cache key to use for an Autocomplete's complete items
     *
     * @param AutocompleteInterface $autocomplete

Missing parameter comment

Tag value for @param tag indented incorrectly; expected 2 spaces but found 1

     * @param array $config

Missing parameter comment

Expected 17 spaces after parameter type; 1 found

Tag value for @param tag indented incorrectly; expected 2 spaces but found 1

     * @return string

Tag @return cannot be grouped with parameter tags in a doc comment

     */
    public function getAutocompleteCacheKey(AutocompleteInterface $autocomplete, array $config): string
    {
        return $this->cacheKeyPrefix . $autocomplete->name . md5(serialize($config));

Accessing name on the interface nystudio107\twigfield\base\AutocompleteInterface suggest that you code against a concrete implementation. How about adding an instanceof check?

    }

    // Protected Methods
    // =========================================================================

    /**

Parameter $fieldType should have a doc-comment as per coding-style.

     * Returns all available autocompletes classes.
     *
     * @return string[] The available autocompletes classes
     */
    public function getAllAutocompleteGenerators(string $fieldType = Twigfield::DEFAULT_FIELD_TYPE): array
    {
        $event = new RegisterTwigfieldAutocompletesEvent([

The opening parenthesis of a multi-line function call should be the last content on the line.

            'types' => Twigfield::$settings->defaultTwigfieldAutocompletes,
            'fieldType' => $fieldType,
        ]);

For multi-line function calls, the closing parenthesis should be on a new line.

        $this->trigger(self::EVENT_REGISTER_TWIGFIELD_AUTOCOMPLETES, $event);

        return $event->types;
    }
}