diff --git a/CHANGELOG.md b/CHANGELOG.md index 680e0c8..a3d59c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## 6.0.0 -Version 6 contains a number of changes to improve the security and performance of the package. Refer to the [UPGRADING.md](UPGRADING.md) file for detailed instructions on how to upgrade from version 5. +Version 6 contains a number of changes to improve the usability, performance and security of the package. Refer to the [UPGRADING.md](UPGRADING.md) file for detailed instructions on how to upgrade from version 5. ### Compatibility @@ -10,8 +10,7 @@ Version 6 contains a number of changes to improve the security and performance o - Droppped support for PHP 8.0 and below - Added support for Laravel 10 and 11 - Dropped support Laravel versions 9 and below -- Adjusted some method signatures with PHP 8+ mixed and union types -- New schema migration adding two new columns and improving indexing for searching by meta values. See [UPGRADING.md](UPGRADING.md) for details +- New schema migration adding new columns and improving indexing for searching by meta values. See [UPGRADING.md](UPGRADING.md) for details ### Data Types @@ -21,10 +20,10 @@ Version 6 contains a number of changes to improve the security and performance o - Added `PureEnumHandler` and `BackedEnumHandler` which adds support for storing enum values as Meta. - Added `StringableHandler` which adds support for storing `Illuminate\Support\Stringable` objects as Meta. - Added `DateTimeImmutableHandler` which adds support for storing `DateTimeImmutable`/`CarbonImmutable` objects as Meta. -- `ModelHandler` will now validate that the encoded class is a valid Eloquent Model before attempting to instantiate it during unserialization. If the class is invalid, the meta value will return `null`. -- `ModelHandler` will no longer throw a model not found exception if the model no longer exists. Instead, the meta value will return `null`. This is more in line with the existing behavior of the `ModelCollectionHandler`. -- `ModelCollectionHandler` will now validate that the encoded collection class is a valid Eloquent collection before attempting to instantiate it during unserialization. If the class is invalid, an instance of `Illuminate\Database\Eloquent\Collection` will be used instead. -- `ModelCollectionHandler` will now validate that the encoded class of each entry is a valid Eloquent Model before attempting to instantiate it during unserialization. If the class is invalid, that entry in the collection will be omitted. +- The `ModelHandler` will now validate that the encoded class is a valid Eloquent Model before attempting to instantiate it during unserialization. If the class is invalid, the meta value will return `null`. +- The `ModelHandler` will no longer throw a model not found exception if the model no longer exists. Instead, the meta value will return `null`. This is more in line with the existing behavior of the `ModelCollectionHandler`. +- The `ModelCollectionHandler` will now validate that the encoded collection class is a valid Eloquent collection before attempting to instantiate it during unserialization. If the class is invalid, an instance of `Illuminate\Database\Eloquent\Collection` will be used instead. +- The `ModelCollectionHandler` will now validate that the encoded class of each entry is a valid Eloquent Model before attempting to instantiate it during unserialization. If the class is invalid, that entry in the collection will be omitted. - Added `getNumericValue(): null|int|float` method to `HandlerInterface` which should convert the original value into a numeric format for indexing, if relevant for the data type. - Added `useHmacVerification(): bool` method to `HandlerInterface` which should indicate whether the integrity of the serialized data should be verified with an HMAC. @@ -34,8 +33,8 @@ Version 6 contains a number of changes to improve the security and performance o ### Efficient Value Search -- The Metable `whereMeta()`, `whereMetaIn()`, and `orderByMeta()` query scopes can now leverage a prefix index on the ``meta.value`` column. This greatly improves performance when searching for meta values against larger datasets when using applicable operators, e.g. `=`, `%`, `>`, `>=`, `<`, `<=`, `<>`, `LIKE` (no leading wildcard). -- `whereMetaNumeric()` and `orderByMetaNumeric()` query scopes will now scan the indexed `numeric_value` column instead of the serialized `value` column. This greatly improves performance when searching for meta values against larger datasets. +- The Metable `whereMeta()`, `whereMetaIn()`, and `orderByMeta()` query scopes can now leverage a prefix index on the ``meta.value`` column. This greatly improves performance when searching for meta values against larger datasets when using applicable operators, e.g. `=`, `%`, `>`, `>=`, `<`, `<=`, `<>`, `LIKE` (no leading wildcard). This index is only supported by the `'mysql'`, `'mariadb'`, `'pgsql'`, and `'sqlite'` drivers. +- The `whereMetaNumeric()` and `orderByMetaNumeric()` query scopes will now scan the indexed `numeric_value` column instead of the serialized `value` column. This greatly improves performance when searching for meta values against larger datasets. - `whereMetaNumeric()` query scope will now accept a value of any type. It will be converted to an integer or float by the handler. This is more consistent with the behaviour of the other query scopes. - Added additional query scopes to more easily search meta values based on different criteria: - `whereMetaInNumeric()` @@ -57,7 +56,7 @@ Version 6 contains a number of changes to improve the security and performance o ### Encrypt Meta - Added the `setMetaEncrypted()` method which will encrypt data before storing it in the database and decrypt it when retrieving it. This is useful for storing sensitive data in the meta table. -- prefixing a meta cast with `encrypted:` will automatically encrypt all values for that meta key. +- Prefixing a meta cast with `encrypted:` will automatically encrypt all values for that meta key. ### Metable Attributes diff --git a/UPGRADING.md b/UPGRADING.md index 4529eaa..5560e8c 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -10,7 +10,8 @@ ### Schema Changes -* A new schema migration has been added which adds three new columns to the meta table and improves indexing for querying by meta values. +* A new schema migration has been added which adds two new columns to the meta table and improves indexing for querying by meta values. +* Before running the migration, you may choose to tune the `metable.stringValueIndexLength` config to adjust the length of the index on the `value` column. The default value of 255 is suitable for most use cases. ### Configuration Changes @@ -36,7 +37,7 @@ ### Metable Attributes -* Optional: if you intend to access meta with property access, add the new `\Plank\Metable\MetableAttributes` traits to your `Metable`. +* (Optional) If you intend to access meta with property access, add the new `\Plank\Metable\MetableAttributes` traits to your `Metable`. ## 4.X -> 5.X - New migration file added which adds a new composite unique index to the meta table on `metable_type`, `metable_id`, and `key`. Make sure that you have no duplicate keys for a given entity (previously possible as a race condition) before applying the new migration. diff --git a/docs/source/datatypes.rst b/docs/source/datatypes.rst index c3b64eb..9b92733 100644 --- a/docs/source/datatypes.rst +++ b/docs/source/datatypes.rst @@ -60,7 +60,7 @@ Null ^^^^^^^^ +----------------------+-----+ | Handler | ``\Plank\Metable\DataType\NullHandler`` | -| String Query Scopes | No | +| String Query Scopes | Yes | | Numeric Query Scopes | No | | Other Query Scopes | whereMetaIsNull() | +----------------------+-----+