Small but useful. Entity class. #1176

system/Entity.php

@@ -221,6 +221,14 @@ public function __set(string $key, $value = null)
 			$value = serialize($value);
 		}
 
+		// JSON casting requires that we JSONize the value
+		// when setting it so that it can easily be stored
+		// back to the database.
+		if (function_exists('json_encode') && array_key_exists($key, $this->_options['casts']) && ($this->_options['casts'][$key] === 'json' || $this->_options['casts'][$key] === 'json-array'))
+		{
+			$value = json_encode($value);
+		}
+
 		// if a set* method exists for this key,

 		// use that method to insert this value.

 		$method = 'set' . str_replace(' ', '', ucwords(str_replace(['-', '_'], ' ', $key)));
@@ -388,6 +396,30 @@ protected function castAs($value, string $type)
 					$value = unserialize($value);
 				}
 
+				$value = (array)$value;
+				break;
+						case 'json':
+				if (function_exists('json_decode') && is_string($value) && (strpos($value, '[') === 0 || strpos($value, '{') === 0))
+				{
+					$value = json_decode($value, false);
+
+					if(json_last_error() !== JSON_ERROR_NONE)
+					{
+						throw CastException::forInvalidJsonFormatException(json_last_error());
+					}
+				}
+				$value = (object)$value;
+				break;
+			case 'json-array':
+				if (function_exists('json_decode') && is_string($value) && (strpos($value, '[') === 0 || strpos($value, '{') === 0))
+				{
+					$value = json_decode($value, true);
+
+					if(json_last_error() !== JSON_ERROR_NONE)
+					{
+						throw CastException::forInvalidJsonFormatException(json_last_error());
+					}
+				}
 				$value = (array)$value;
 				break;
 			case 'datetime':

system/Exceptions/CastException.php

@@ -0,0 +1,40 @@
+<?php namespace CodeIgniter\Exceptions;
+
+/**
+ * Cast Exceptions.
+ */
+class CastException extends CriticalError
+{
+
+	/**
+	 * Error code
+	 * @var int
+	 */
+	protected $code = 3;
+
+	public static function forInvalidJsonFormatException(int $error)
+	{	
+		switch($error)
+		{
+			case JSON_ERROR_DEPTH:
+				throw new static(lang('Cast.jsonErrorDepth'));
+				break;
+			case JSON_ERROR_STATE_MISMATCH:
+				throw new static(lang('Cast.jsonErrorStateMismatch'));
+				break;
+			case JSON_ERROR_CTRL_CHAR:
+				throw new static(lang('Cast.jsonErrorCtrlChar'));
+				break;
+			case JSON_ERROR_SYNTAX:
+				throw new static(lang('Cast.jsonErrorSyntax'));
+				break;
+			case JSON_ERROR_UTF8:
+				throw new static(lang('Cast.jsonErrorUtf8'));
+				break;
+			default:
+				throw new static(lang('Cast.jsonErrorUnknown'));
+		}
+
+	}
+
+}

system/Language/en/Cast.php

@@ -0,0 +1,23 @@
+<?php
+/**
+ * Cast language strings.
+ *
+ * @package      CodeIgniter
+ * @author       CodeIgniter Dev Team
+ * @copyright    2014-2018 British Columbia Institute of Technology (https://bcit.ca/)
+ * @license      https://opensource.org/licenses/MIT	MIT License
+ * @link         https://codeigniter.com
+ * @since        Version 3.0.0
+ * @filesource
+ * 
+ * @codeCoverageIgnore
+ */
+
+return [
+	'Cast.jsonErrorDepth' 		=> 'Maximum stack depth exceeded',
+	'Cast.jsonErrorStateMismatch'	=> 'Underflow or the modes mismatch',
+	'Cast.jsonErrorCtrlChar'	=> 'Unexpected control character found',
+	'Cast.jsonErrorSyntax'		=> 'Syntax error, malformed JSON',
+	'Cast.jsonErrorUtf8'		=> 'Malformed UTF-8 characters, possibly incorrectly encoded',
+	'Cast.jsonErrorUnknown'		=> 'Unknown error'
+];

user_guide_src/source/database/entities.rst

@@ -337,12 +337,22 @@ For example, if you had a User entity with an **is_banned** property, you can ca
         ];
     }
 
-Array Casting
+Array/Json Casting
 -------------
 
-Array casting is especially useful with fields that store serialized arrays or json in them. When cast as an array,
-they will automatically be unserialized when you read the property's value. Unlike the rest of the data types that
-you can cast properties into, the **array** cast type will serialize the value whenever the property is set::
+Array/Json casting is especially useful with fields that store serialized arrays or json in them. When cast as:
+
+* an **array**, they will automatically be unserialized,
+* a **json**, they will automatically be set as an value of json_decode($value, false),
+* a **json-array**, they will automatically be set as an value of  json_decode($value, true),
+
+when you read the property's value.
+Unlike the rest of the data types that you can cast properties into, the:
+
+* **array** cast type will serialize,
+* **json** and **json-array** cast will use json_encode function on
+
+the value whenever the property is set::
 
     <?php namespace App\Entities;
 
@@ -354,7 +364,9 @@ you can cast properties into, the **array** cast type will serialize the value w
 
         protected $_options = [
             'casts' => [
-                'options' => 'array'
+                'options' => 'array',
+		'options_object' => 'json',
+		'options_array' => 'json-array'
             ],
              'dates' => ['created_at', 'updated_at', 'deleted_at'],
             'datamap' => []