nystudio107 / craft-code-field

src/fields/Code.php

<?php
/**
 * Code Field plugin for Craft CMS
 *
 * Provides a Code Field that has a full-featured code editor with syntax highlighting & 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\codefield\fields;

use Craft;
use craft\base\ElementInterface;

The type craft\base\ElementInterface was not found. Maybe you did not declare it correctly or list all dependencies?

use craft\base\Field;
use craft\base\PreviewableFieldInterface;
use craft\helpers\Html;
use craft\helpers\Json;
use craft\validators\ArrayValidator;
use GraphQL\Type\Definition\Type;
use nystudio107\codefield\gql\types\generators\CodeDataGenerator;
use nystudio107\codefield\models\CodeData;
use nystudio107\codefield\validators\JsonValidator;
use yii\db\Schema;
use function is_array;
use function is_string;

/**

Missing short description in doc comment

 * @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   CodeField

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

 * @since     4.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 Code extends Field implements PreviewableFieldInterface
{
    // Constants
    // =========================================================================

    /**
     * Properties that are no longer used, but may still be passed into the $config
     * via __construct() that we should remove to avoid throwing an exception
     */
    protected const DEPRECATED_PROPERTIES = [
        'columnType',
    ];

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

    /**

Missing short description in doc comment

     * @var string The theme to use for the Code Editor field.
     */
    public string $theme = 'auto';

    /**

Missing short description in doc comment

     * @var string The language to use for the Code Editor field.
     */
    public string $language = 'javascript';

    /**

Missing short description in doc comment

     * @var bool Whether the Code Editor field display as a single line
     */
    public bool $singleLineEditor = false;

    /**

Missing short description in doc comment

     * @var int The font size to use for the Code Editor field
     */
    public int $fontSize = 14;

    /**

Missing short description in doc comment

     * @var bool Whether line numbers should be displayed in the Code Editor field
     */
    public bool $lineNumbers = false;

    /**

Missing short description in doc comment

     * @var bool Whether code folding should be used in the Code Editor field
     */
    public bool $codeFolding = false;

    /**

Missing short description in doc comment

     * @var string The text that will be shown if the code field is empty.
     */
    public string $placeholder = '';

    /**

Missing short description in doc comment

     * @var bool Whether the language selector dropdown menu should be displayed.
     */
    public bool $showLanguageDropdown = true;

    /**

Missing short description in doc comment

     * @var string The default value the Code Field will be populated with
     */
    public string $defaultValue = '';

    /**

Missing short description in doc comment

     * @var array The languages that should be listed in the language selector dropdown menu.
     */
    public array $availableLanguages = [
        'css',
        'graphql',
        'html',
        'javascript',
        'json',
        'markdown',
        'mysql',
        'php',
        'shell',
        'twig',
        'typescript',
        'yaml',
    ];

    /**

Missing short description in doc comment

     * @var string JSON blob of Monaco [EditorOptions](https://microsoft.github.io/monaco-editor/api/interfaces/monaco.editor.IEditorOptions.html) that will override the default settings
     */
    public string $monacoEditorOptions = '';

    // Static Methods
    // =========================================================================

    /**

Missing short description in doc comment

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

     * @inheritdoc
     */
    public function __construct(array $config = [])
    {
        // Unset any deprecated properties
        foreach (self::DEPRECATED_PROPERTIES as $deprecatedProperty) {
            unset($config[$deprecatedProperty]);
        }
        parent::__construct($config);
    }

    /**

Missing short description in doc comment

     * @inheritdoc
     */

Missing @return tag in function comment

    public static function dbType(): array|string|null
    {
        return Schema::TYPE_TEXT;
    }

    /**

Missing short description in doc comment

     * @inheritdoc
     */

Missing @return tag in function comment

    public static function icon(): string
    {
        return 'code';
    }

    /**

Missing short description in doc comment

     * @inheritdoc
     */

Missing @return tag in function comment

    public static function displayName(): string
    {
        return Craft::t('codefield', 'Code');
    }

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

    /**

Missing short description in doc comment

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

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

     * @inheritdoc
     */

Missing @return tag in function comment

    public function normalizeValue(mixed $value, ?ElementInterface $element = null): mixed
    {
        if ($value instanceof CodeData) {
            return $value;
        }
        // Default config
        $config = [
            'value' => $this->defaultValue,
            'language' => $this->language,
        ];
        // Handle incoming values potentially being JSON or an array
        if (!empty($value)) {
            // Handle JSON-encoded values coming in
            if (is_string($value)) {
                $jsonValue = Json::decodeIfJson($value);
                // If this is still a string (meaning it's not valid JSON), treat it as the value
                if (is_string($jsonValue)) {
                    $config['value'] = $jsonValue;
                }
                if (is_array($jsonValue)) {
                    // Check to make sure the array returned is an encoded `CodeData` config, with exactly
                    // the same expected key/value pairs
                    if (!array_diff_key($config, $jsonValue) && !array_diff_key($jsonValue, $config)) {
                        $value = $jsonValue;
                    } else {
                        // Otherwise treat it as JSON data
                        $value = [
                            'value' => $value,
                            'language' => 'json',
                        ];
                    }
                }
            }
            if (is_array($value)) {
                $config = array_merge($config, array_filter($value));
            }
        }
        // Create and validate the model
        $codeData = new CodeData($config);
        if (!$codeData->validate()) {
            Craft::error(
                Craft::t('codefield', 'CodeData failed validation: ')
                . print_r($codeData->getErrors(), true),

Are you sure print_r($codeData->getErrors(), true) of type string|true can be used in concatenation?

                __METHOD__
            );
        }

        return $codeData;
    }

    /**

Missing short description in doc comment

     * @inheritdoc
     */

Missing @return tag in function comment

    public function getSettingsHtml(): ?string
    {
        $monacoLanguages = require(__DIR__ . '/MonacoLanguages.php');

"require" is a statement not a function; no parentheses are required

File is being conditionally included; use "include" instead

        $schemaFilePath = Craft::getAlias('@nystudio107/codefield/resources/IEditorOptionsSchema.json');
        $optionsSchema = @file_get_contents($schemaFilePath) ?: '';

It seems like $schemaFilePath can also be of type false; however, parameter $filename of file_get_contents() does only seem to accept string, maybe add an additional type check?

        // Render the settings template
        return Craft::$app->getView()->renderTemplate(
            'codefield/_components/fields/Code_settings',
            [
                'field' => $this,
                'monacoLanguages' => $monacoLanguages,
                'optionsSchema' => $optionsSchema,
            ]
        );
    }

    /**

Missing short description in doc comment

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

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

     * @inheritdoc
     */

Missing @return tag in function comment

    public function getInputHtml($value, ElementInterface $element = null): string
    {
        $twigVariables = $this->getFieldRenderVariables($value, $element, true);

It seems like $element can also be of type null; however, parameter $element of nystudio107\codefield\fields\Code::getFieldRenderVariables() does only seem to accept craft\base\ElementInterface, maybe add an additional type check?

        // Render the input template
        return Craft::$app->getView()->renderTemplate(
            'codefield/_components/fields/Code_input',
            $twigVariables
        );
    }

    /**

Missing short description in doc comment

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

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

     * @inheritdoc
     */

Missing @return tag in function comment

    public function getStaticHtml(mixed $value, ElementInterface $element): string
    {
        $twigVariables = $this->getFieldRenderVariables($value, $element, false);
        // Render the input template
        return Craft::$app->getView()->renderTemplate(
            'codefield/_components/fields/Code_input',
            $twigVariables
        );
    }

    /**

Missing short description in doc comment

     * @inheritdoc
     */

Missing @return tag in function comment

    public function getContentGqlType(): Type|array
    {
        $typeArray = CodeDataGenerator::generateTypes($this);

        return [
            'name' => $this->handle,
            'description' => 'Code Editor field',
            'type' => array_shift($typeArray),
        ];
    }

    /**

Missing short description in doc comment

     * @inheritdoc
     */

Missing @return tag in function comment

    public function rules(): array
    {
        $rules = parent::rules();
        return array_merge($rules, [

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

            ['theme', 'in', 'range' => ['auto', 'vs', 'vs-dark', 'hc-black']],
            ['theme', 'default', 'value' => 'auto'],
            ['language', 'string'],
            ['language', 'default', 'value' => 'javascript'],
            [['singleLineEditor', 'showLanguageDropdown', 'lineNumbers', 'codeFolding'], 'boolean'],
            ['placeholder', 'string'],
            ['placeholder', 'default', 'value' => ''],
            ['fontSize', 'integer'],
            ['fontSize', 'default', 'value' => 14],
            ['availableLanguages', ArrayValidator::class],
            ['monacoEditorOptions', JsonValidator::class],
        ]);

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

    }

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

    /**
     * Return the Twig variables for rendering the field
     *
     * @param $value

Missing parameter comment

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

     * @param ElementInterface $element

Missing parameter comment

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

     * @param bool $enabled Whether the field is enabled or not

Expected 13 spaces after parameter type; 1 found

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

     */
    protected function getFieldRenderVariables($value, ElementInterface $element, bool $enabled): array
    {
        // Get our id and namespace
        $id = Html::id($this->handle);
        $namespacedId = Craft::$app->getView()->namespaceInputId($id);

        // Extract just the languages that have been selected for display
        $displayLanguages = [];
        if ($this->showLanguageDropdown) {
            $monacoLanguages = require(__DIR__ . '/MonacoLanguages.php');

"require" is a statement not a function; no parentheses are required

File is being conditionally included; use "include" instead

            $decomposedLanguages = array_column($monacoLanguages, 'label', 'value');
            $displayLanguages = array_intersect_key($decomposedLanguages, array_flip($this->availableLanguages));
            // Handle "all" checkbox
            if ($this->availableLanguages[0] === '*') {
                $displayLanguages = $decomposedLanguages;
            }
            $displayLanguages = array_map(static function($k, $v) {

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

Expected 1 space after FUNCTION keyword; 0 found

                return ['value' => $k, 'label' => $v];
            }, array_keys($displayLanguages), array_values($displayLanguages));

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

        }
        $monacoOptionsOverride = Json::decodeIfJson($this->monacoEditorOptions);
        if ($monacoOptionsOverride === null || is_string($monacoOptionsOverride)) {
            $monacoOptionsOverride = [];
        }
        // Disable the Monaco editor
        if (!$enabled) {
            $monacoOptionsOverride['domReadOnly'] = true;
            $monacoOptionsOverride['readOnly'] = true;
        }
        return [

The expression return array('name' => $this->handle, 'value' => $value, 'field' => $this, 'orientation' => $this->getOrientation($element), 'id' => $id, 'namespacedId' => $namespacedId, 'displayLanguages' => $displayLanguages, 'monacoOptionsOverride' => $monacoOptionsOverride) returns an array which contains values of type nystudio107\codefield\fields\Code|string which are incompatible with the documented value type array.

            'name' => $this->handle,
            'value' => $value,
            'field' => $this,
            'orientation' => $this->getOrientation($element),
            'id' => $id,
            'namespacedId' => $namespacedId,
            'displayLanguages' => $displayLanguages,
            'monacoOptionsOverride' => $monacoOptionsOverride,
        ];
    }
}