Merge branch 'release/2.0.0'

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2.0.0 - 2022-08-08
+### Added
+- Initial Craft 4 release
+
 ## 1.4.0 - 2022-08-08
 ### Added
 - Added support for craft-twigfield ([#81](https://github.com/besteadfast/craft-preparse-field/pull/81) - thanks @khalwat)

README.md

@@ -4,83 +4,76 @@ A fieldtype that parses Twig when an element is saved and saves the result as pl
 
 ## Requirements
 
-This plugin requires Craft CMS 3.2.0 or later.
-
-_The Craft 2 version can be found in the [craft2](https://github.com/besteadfast/craft-preparse-field/tree/craft2) branch_
+This plugin requires Craft CMS 4.0.0 or later and PHP 8.0.2 or later.
 
 ## Installation
 
 To install the plugin, follow these instructions.
 
-1.  Open your terminal and go to your Craft project:
+1. Open your terminal and go to your Craft project:
 
   cd /path/to/project
 
-2.  Then tell Composer to load the plugin:
+2. Then tell Composer to load the plugin:
 
   composer require besteadfast/craft-preparse-field
 
-3.  In the Control Panel, go to Settings → Plugins and click the “Install” button for Preparse Field.
+3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Preparse Field.
 
 ## Usage
 
-When creating a new Preparse field, you can add the Twig that you want to run to the fields settings. When an element with a preparse field is saved, the code will be parsed. The element itself is available as `element` in twig.
+When creating a new Preparse field, you add the Twig that you want run to the field's settings. When an element with that Preparse field is saved, the code will be parsed and the resulting value saved as plain text.
+
+It's worth noting that the Preparse field is only updated when the element the field is on is saved. If you grab data from a related element (like in the category title example below), and then update the related element, the preparsed value will not automatically be updated.
 
-**Usage in Matrix** 
-When a Preparse field is added to a Matrix block, that block will be available to the Twig code as the variable `element`. The element that the Matrix field belongs to will be available under `element.owner`.
+In the Twig, the element that the Preparse field is added to is available as a variable named `element`. It's best to use this variable (as opposed to something like `entry` or `asset`) because it's possible you add the same Preparse field to multiple element types. This also means that when a Preparse field is added to a Matrix, SuperTable, or Neo block, that block will be what is available as `element`, so if you want to access the element that the Matrix/SuperTable/Neo field belongs to, you will want to use `element.owner`.
 
 ### Examples
 
-If you have a category field in your entry named `entryCategory`, you can save the category title to the preparse field by adding the following Twig to the field settings:
+If you have a category field on your element named `relatedCategory`, you can save the category title to the Preparse field by adding the following Twig to the field settings:
 
- {{ element.entryCategory | length ? element.entryCategory.first().title }}
+ {{ element.relatedCategory.one().title ?? '' }}
 
-This is useful for saving preparsed values to a field for use with sorting, searching or similar things.
+This is useful for saving preparsed values to a field for use with sorting, searching, or similar things.
 
-You can also do more advanced stuff, for instance for performance optimizing. Let's say you have three different asset fields that may or may not be populated. having to check these in the template may require a bunch of queries since you can't check if a field has a relation in Craft, without actually querying for it. You could do something like this to get the id of the asset to use:
+You can also do more advanced stuff, for instance performance optimizing. Let's say you have three different asset fields that may or may not be populated. Having to check these in the template may require a bunch of queries since you can't check if a field has a relation in Craft without actually querying for it. You could do something like this to get the id of the asset to use:
 
  {% if element.smallListImage | length %}
-  {{ element.smallListImage.first().id }}
+  {{ element.smallListImage.one().id }}
  {% elseif element.largeListImage | length %}
-  {{ element.largeListImage.first().id }}
+  {{ element.largeListImage.one().id }}
  {% elseif element.mainImage | length %}
-  {{ element.mainImage.first().id }}
- {% endif %}
-
-You'd probably want to wrap that in `{% spaceless %} ... {% endspaceless %}` to make it more useful.
-
-Or you could just use it to do some bulk work when saving, like pre-generating a bunch of image transforms with [Imager](https://github.com/aelvan/Imager-Craft):
-
- {% if element.image | length %}
-  {% set transformedImages = craft.imager.transformImage(element.image.first(), [
-  { width: 1000 },
-  { width: 900 },
-  { width: 800 },
-  { width: 700 },
-  { width: 600 },
-  { width: 500 },
-  { width: 400 },
-  { width: 300 },
-  { width: 200 },
-  { width: 100 }
-  ]) %}
+  {{ element.mainImage.one().id }}
  {% endif %}
 
-The template path is set to your site template path, so you can even include whole templates if you want to do more advanced stuff and/or want to keep your fields Twig in version control:
-{% include '_fields/myFieldInclude' %}
-Make sure that you always write solid Twig, taking into account that fields may not be populated yet. If an error occurs in your Twig, the element will not be saved.
-
-## Cache gotchas
+_You'd probably want to wrap that in `{% apply spaceless %} ... {% endapply %}` to make it more useful..._
+
+Or you could just use it to do some bulk work when saving, like pre-generating a bunch of image transforms with [Imager X](https://plugins.craftcms.com/imager-x?craft4):
+
+ {% if element.mainImage | length %}
+  {% set transformedImages = craft.imager.transformImage(element.mainImage.one(), [
+  { width: 1000 },
+  { width: 900 },
+  { width: 800 },
+  { width: 700 },
+  { width: 600 },
+  { width: 500 },
+  { width: 400 },
+  { width: 300 },
+  { width: 200 },
+  { width: 100 }
+  ]) %}
+ {% endif %}
 
-The preparse field is only updated when an element is saved. If you grab data from a related element (like in the category title example above), and then update the related element, the preparsed value will not automatically be updated.
+Preparse also has access to your site's template root, so you can even include local templates if you want to do more advanced stuff and/or want to keep your field's Twig in version control:
 
-## Locales gotchas
+ {% include '_partials/customPreparseFieldStuff' %}
 
-The preparse field is made to work with localized sites, but there is one gotcha. It is important that the fields that you process, and the preparse field itself, has the same locales setup. If the target field is set up to be localized to two different languages, and your preparse field is not, the value will be updated to the target field value in the language that was saved last. If your target field is not localized, but you localize your preparse field, you will need to save the entry in both languages if you change the target field.
+Make sure that you always write solid Twig, taking into account that fields may not be populated yet. If an error occurs in your Twig, the element will not be saved. [Code defensively!](https://nystudio107.com/blog/handling-errors-gracefully-in-craft-cms#defensive-coding-in-twig)
 
-## Price, license and support
+## Price, License, and Support
 
-The plugin is released under the MIT license, meaning you can do whatever you want with it as long as you don't blame us. **It's free**, which means there is absolutely no support included, but you might get it anyway. Just post an issue here on github if you have one, and we'll see what we can do. :)
+The plugin is released under the MIT license, meaning you can do whatever you want with it as long as you don't blame us. **It's free**, which means there is absolutely no support included, but you might get it anyway. Just post an issue here on GitHub if you have one, and we'll see what we can do. :)
 
 ## Changelog
 

composer.json

@@ -2,7 +2,7 @@
  "name": "besteadfast/craft-preparse-field",
  "description": "A fieldtype that parses Twig when an element is saved and saves the result as plain text.",
  "type": "craft-plugin",
- "version": "1.4.0",
+ "version": "2.0.0",
  "keywords": [
  "craft",
  "cms",
@@ -28,13 +28,13 @@
  }
  ],
  "require": {
- "craftcms/cms": "^3.2.0",
- "nystudio107/craft-twigfield": "^1.0.0"
+ "craftcms/cms": "^4.0.0",
+ "nystudio107/craft-twigfield": "^1.0.0",
+ "php": "^8.0.2"
  },
  "autoload": {
  "psr-4": {
- "besteadfast\\preparsefield\\": "src/",
- "aelvan\\preparsefield\\": "src_legacy/"
+ "besteadfast\\preparsefield\\": "src/"
  }
  },
  "extra": {

src/PreparseField.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Preparse Field plugin for Craft CMS 3.x
+ * Preparse Field plugin for Craft CMS 4.x
  *
  * @link https://www.steadfastdesignfirm.com/
  * @copyright Copyright (c) Steadfast Design Firm
@@ -10,7 +10,6 @@
 
 use besteadfast\preparsefield\fields\PreparseFieldType;
 use besteadfast\preparsefield\services\PreparseFieldService as PreparseFieldServiceService;
-
 use Craft;
 use craft\base\Element;
 use craft\base\Plugin;
@@ -22,9 +21,9 @@
 use craft\services\Elements;
 use craft\services\Fields;
 use craft\events\RegisterComponentTypesEvent;
-
 use craft\services\Structures;
 use craft\web\UploadedFile;
+use Exception;
 use yii\base\Event;
 
 /**
@@ -44,14 +43,14 @@ class PreparseField extends Plugin
  *
  * @var PreparseField
  */
- public static $plugin;
+ public static PreparseField $plugin;
 
  /**
  * Stores the IDs of elements we already preparsed the fields for.
  *
  * @var array
  */
- public $preparsedElements;
+ public array $preparsedElements;
 
  /**
  * Plugin init method
@@ -178,15 +177,15 @@ function (MoveElementEvent $event) {
  * @param string $level
  * @param string $file
  */
- public static function log($msg, $level = 'notice', $file = 'Preparse')
+ public static function log($msg, string $level = 'notice', string $file = 'Preparse')
  {
  try
  {
  $file = Craft::getAlias('@storage/logs/' . $file . '.log');
  $log = "\n" . date('Y-m-d H:i:s') . " [{$level}]" . "\n" . print_r($msg, true);
  FileHelper::writeToFile($file, $log, ['append' => true]);
  }
- catch(\Exception $e)
+ catch(Exception $e)
  {
  Craft::error($e->getMessage());
  }
@@ -197,7 +196,7 @@ public static function log($msg, $level = 'notice', $file = 'Preparse')
  * @param string $level
  * @param string $file
  */
- public static function error($msg, $level = 'error', $file = 'RecurringOrders')
+ public static function error($msg, string $level = 'error', string $file = 'Preparse')
  {
  static::log($msg, $level, $file);
  }

src/fields/PreparseFieldType.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Preparse Field plugin for Craft CMS 3.x
+ * Preparse Field plugin for Craft CMS 4.x
  *
  * @link https://www.steadfastdesignfirm.com/
  * @copyright Copyright (c) Steadfast Design Firm
@@ -20,10 +20,12 @@
 use craft\helpers\DateTimeHelper;
 use craft\helpers\Db;
 use craft\i18n\Locale;
+use GraphQL\Type\Definition\Type;
 use Twig\Error\LoaderError;
 use Twig\Error\RuntimeError;
 use Twig\Error\SyntaxError;
 use yii\base\Exception;
+use yii\base\InvalidConfigException;
 
 /**
  * Preparse field type
@@ -45,15 +47,15 @@ class PreparseFieldType extends Field implements PreviewableFieldInterface, Sort
  *
  * @var string
  */
- public $fieldTwig = '';
- public $displayType = 'hidden';
- public $showField = false;
- public $columnType = Schema::TYPE_TEXT;
- public $decimals = 0;
- public $textareaRows = 5;
- public $parseBeforeSave = false;
- public $parseOnMove = false;
- public $allowSelect = false;
+ public string $fieldTwig = '';
+ public string $displayType = 'hidden';
+ public bool $showField = false;
+ public string $columnType = Schema::TYPE_TEXT;
+ public int $decimals = 0;
+ public int $textareaRows = 5;
+ public bool $parseBeforeSave = false;
+ public bool $parseOnMove = false;
+ public bool $allowSelect = false;
 
  // Static Methods
  // =========================================================================
@@ -71,7 +73,7 @@ public static function displayName(): string
  // Public Methods
  // =========================================================================
 
- public function rules()
+ public function rules(): array
  {
  $rules = parent::rules();
  return array_merge($rules, [
@@ -94,11 +96,11 @@ public function rules()
  ]);
  }
 
- /**
- * @return string
-  * @throws Exception
-  */
- public function getContentColumnType(): string
+ /**
+ * @return array|string
+  * @throws Exception
+  */
+ public function getContentColumnType(): array|string
  {
  if ($this->columnType === Schema::TYPE_DECIMAL) {
  return Db::getNumericalColumnType(null, null, $this->decimals);
@@ -111,9 +113,9 @@ public function getContentColumnType(): string
  * @return null|string
  * @throws LoaderError
  * @throws RuntimeError
- * @throws SyntaxError
+ * @throws SyntaxError|Exception
  */
- public function getSettingsHtml()
+ public function getSettingsHtml(): ?string
  {
  $columns = [
  Schema::TYPE_TEXT => Craft::t('preparse-field', 'Text (stores about 64K)'),
@@ -149,9 +151,9 @@ public function getSettingsHtml()
  * @return string
  * @throws LoaderError
  * @throws RuntimeError
- * @throws SyntaxError
+ * @throws SyntaxError|Exception
  */
- public function getInputHtml($value, ElementInterface $element = null): string
+ public function getInputHtml(mixed $value, ?ElementInterface $element = null): string
  {
  // Get our id and namespace
  $id = Craft::$app->getView()->formatInputId($this->handle);
@@ -178,7 +180,7 @@ public function getInputHtml($value, ElementInterface $element = null): string
  /**
  * @inheritdoc
  */
- public function getSearchKeywords($value, ElementInterface $element): string
+ public function getSearchKeywords(mixed $value, ElementInterface $element): string
  {
  if ($this->columnType === Schema::TYPE_DATETIME) {
  return '';
@@ -188,8 +190,9 @@ public function getSearchKeywords($value, ElementInterface $element): string
 
  /**
  * @inheritdoc
- */
- public function getTableAttributeHtml($value, ElementInterface $element): string
+ * @throws InvalidConfigException
+ */
+ public function getTableAttributeHtml(mixed $value, ElementInterface $element): string
  {
  if (!$value) {
  return '';
@@ -202,10 +205,11 @@ public function getTableAttributeHtml($value, ElementInterface $element): string
  return parent::getTableAttributeHtml($value, $element);
  }
 
- /**
- * @inheritdoc
- */
- public function normalizeValue($value, ElementInterface $element = null)
+ /**
+ * @inheritdoc
+ * @throws \Exception
+ */
+ public function normalizeValue(mixed $value, ?ElementInterface $element = null): mixed
  {
  if ($this->columnType === Schema::TYPE_DATETIME) {
  if ($value && ($date = DateTimeHelper::toDateTime($value)) !== false) {
@@ -219,28 +223,25 @@ public function normalizeValue($value, ElementInterface $element = null)
  /**
  * @inheritdoc
  */
- public function modifyElementsQuery(ElementQueryInterface $query, $value)
+ public function modifyElementsQuery(ElementQueryInterface $query, mixed $value): void
  {
  if ($this->columnType === Schema::TYPE_DATETIME) {
  if ($value !== null) {
  /** @var ElementQuery $query */
  $query->subQuery->andWhere(Db::parseDateParam('content.' . Craft::$app->getContent()->fieldColumnPrefix . $this->handle, $value));
  }
- return null;
  }
- return parent::modifyElementsQuery($query, $value);
+ parent::modifyElementsQuery($query, $value);
  }
 
  /**
  * @inheritdoc
  */
- public function getContentGqlType()
+ public function getContentGqlType(): Type|array
  {
  if ($this->columnType === Schema::TYPE_DATETIME) {
  return DateTimeType::getType();
  }
  return parent::getContentGqlType();
  }
 }
-
-class_alias(PreparseFieldType::class, \aelvan\preparsefield\fields\PreparseFieldType::class);