PHPackages piggly/php-value-types - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. piggly/php-value-types ActiveLibrary[Database & ORM](/categories/database) piggly/php-value-types ====================== Immutable value objects to easy format and assert values. 1.1.0(4y ago)09MITPHPPHP ^7.2 || ^8.0 Since Jun 19Pushed 4y agoCompare [ Source](https://github.com/piggly-dev/php-value-types)[ Packagist](https://packagist.org/packages/piggly/php-value-types)[ Docs](https://github.com/piggly-dev/php-value-types)[ RSS](/packages/piggly-php-value-types/feed)WikiDiscussions dev Synced 1mo ago READMEChangelogDependencies (4)Versions (4)Used By (0) Values objects with based in data types ======================================= [](#values-objects-with-based-in-data-types) [![Versão Atual](https://camo.githubusercontent.com/03f9b3b725fc915ccac58ee9988232b955335c5f85355b00aa42ec684430f8ab/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e782e782d677265656e3f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/03f9b3b725fc915ccac58ee9988232b955335c5f85355b00aa42ec684430f8ab/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e782e782d677265656e3f7374796c653d666c61742d737175617265) [![Latest Version on Packagist](https://camo.githubusercontent.com/56d938d6849a549ef7335823eec6699a39d1ae26486154ecd5c37d3363679cde/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f706967676c792f7068702d76616c75652d74797065732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/piggly/php-value-types) [![Packagist Downloads](https://camo.githubusercontent.com/e358bc302bf789642dd8576ce6cc62cf68e7ff650e433c3ec4be1d9c5bedb4c6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f706967676c792f7068702d76616c75652d74797065733f7374796c653d666c61742d737175617265)](https://packagist.org/packages/piggly/php-value-types) [![Packagist Stars](https://camo.githubusercontent.com/5661b1490894999a00c36f69a6731dc455a49e4ccb1a70ab9a80825e40175d5d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f706967676c792f7068702d76616c75652d74797065733f7374796c653d666c61742d737175617265)](https://packagist.org/packages/piggly/php-value-types) [![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE) [![PHP](https://camo.githubusercontent.com/004aac162ade4228852410dd49dbf166e2fdbbf4e87c434cd852c4f2314b41e5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f706967676c792f7068702d76616c75652d74797065733f7374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/004aac162ade4228852410dd49dbf166e2fdbbf4e87c434cd852c4f2314b41e5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f706967676c792f7068702d76616c75652d74797065733f7374796c653d666c61742d737175617265) This library was developed mainly to API systems. But, it may be applied to any systems. What is Value Object? --------------------- [](#what-is-value-object) A value object is a small object that represents a simple entity whose equality is not based on identity: i.e. two value objects are equal when they have the same value, not necessarily being the same object. Examples of value objects are objects representing an amount of money or a date range. [See more](https://en.wikipedia.org/wiki/Value_object#:~:text=In%20computer%20science%2C%20a%20value,money%20or%20a%20date%20range.). Installation ------------ [](#installation) ### Composer [](#composer) 1. At you console, in your project folder, type `composer require piggly/php-value-types`; 2. Don't forget to add Composer's autoload file at your code base `require_once('vendor/autoload.php);`. ### Manual install [](#manual-install) 1. Download or clone with repository with `git clone https://github.com/piggly-dev/php-value-types.git`; 2. After, goes to `cd /path/to/piggly/php-value-types`; 3. Install all Composer's dependencies with `composer install`; 4. Add project's autoload file at your code base `require_once('/path/to/piggly/php-value-types/vendor/autoload.php);`. Dependencies ------------ [](#dependencies) The library has the following external dependencies: - PHP 7.2+. How can it help? ---------------- [](#how-can-it-help) Imagine an application which handle e-mails. E-mails, even with different values, have the same behavior. They have a pattern and must always be an e-mail. Across your application services, they are many entities with e-mails, such as: users, orders, companies and so on. Without value objects you may need, in any entity which e-mails are available, checking the e-mail pattern. But, with a value object you may set this behavior and instead usign a primite type as string, you will use the `EmailType` object. Any point of your application, it will know by all that `EmailType` handle an e-mail and always return a valid e-mail. Your business logic does not need to care about how to handle e-mails, because you `EmailType` object does. How this library work? ---------------------- [](#how-this-library-work) Into the API enviroment, they are lot of data we can handle. But not just the pure data, but sometimes we must check if data is filled when required or if data meets the requirements of limit, length and so on. This library standartize different values types as objects. And any value object may have one or more assertions to be a valid data as expected by your type. This make the process of validation fast and consisious, where you API must not care about how to handle data, because values objects do. Any value object must extends `AbstractValueType` which consist of an immutable `$value` that once is set, will never change and must be the expected value type. The `AbstractValueType` take care of object assertions, setting a default value or convert any child class to a `string` with `__toString()` method. How do assertions work? ----------------------- [](#how-do-assertions-work) Assertions are runned by three methods: - `validate()`, will always return a `boolean` indicating `true` when all assertions were pass, or `false` if any assertion has failed; - `caught()`, have the same behavior of `validate()` method, but instead of returning `false` if any assertion has failed, it will return a `string` with the message that asserting produced; - `assert()`, will always throw an `InvalidValueTypeOfException` if any assertion fail. You can add assertions to a value type object by using the `apply( $rule )` method. The `$rule` method, must be an object which implements `Piggly\ValueTypes\Interfaces\Validatable` or `Respect\Validation\Validatable` inteface. By default, objects may implement assertions at `constructor` method. ### The *required* behavior [](#the-required-behavior) The only assertion implemented to any `AbstractValueType` is the *required* behavior. When constructing a value type object you may set the `$required` argument as `true`. If this happen, then `AbstractValueType` will evaluate if `$value` is `null` and **required** to throw `InvalidValueTypeOfException` before any assertions, or when `$value` is `null` but **not required** will assert value stopping any other assertions. ### Assertion caching [](#assertion-caching) Since a value object is immutable, the assertion must run only once. So, after run the fisrt time they are cached, and even you call any assertion method it will always return the same result. But, there is an exception. If you apply a new assertion to the value object, it will lose cache and run only once again. Common Objects -------------- [](#common-objects) Basically, the common objects take care about parsing. They will always parse any `$value` you set at `constructor` to expected data type. There are six common objects, they extends and replaces the primitive data types. See: - `ArrayType` handle any `$value` parsing it to a valid `array` primitive type. It can handle even `JSON` strings and objects with any of following methods: `toArray()`, `toJson()` and `jsonSerialize()`; - `BooleanType` handle any `$value` parsing it to a valid `boolean` primitive type; - `FloatType` and `IntegerType` handle any `$value` parsing it to a valid `float` and `integer` primitive types respectively; - `JsonType` handle any `$value` which include parsing it to a valid `JSON` into a `string` primitive type. It can handle `JSON` strings and objects with any of following methods: `toArray()`, `toJson()` and `jsonSerialize()`; - `StringObject` handle any `$value` parsing it to a valid `string` primitive type. It will convery anything to a `string`, even objects which implements `__toString()` method or not. The `ArrayType` and `JsonType` are the only value types that will throw an `InvalidValueTypeOfException` at `constructor` if they can't parse `value` to the expected type. Advanced Objects ---------------- [](#advanced-objects) They are self explainer, different than **Common Objects** they handle more specific behaviors and patterns. See: - `CnhType`, expecting a Brazilian driver's license; - `CnpjType`, expecting a Brazilian National Registry of Legal Entities (CNPJ) number; - `CountryCodeType`, expecting a country code in ISO 3166-1 standard; - `CpfType`, expecting a Brazillian CPF number; - `CreditCardType`, expecting a credit card number; - `CurrencyCodeType`, expecting an ISO 4217 currency code like GBP or EUR; - `DateTimeType`, expecting any date time value; - `DateType`, expecting any date value; - `DigitsType`, expecting a `string` with only digits; - `EmailType`, expecting an e-mail; - `HexRgbColorType`, expecting a hexadecimal to RGB color; - `IpType`, expecting an IP; - `PasswordType`, expecting a password. It has enhanced behavior, see below; - `PhoneType`, expecting a phone number; - `PostalCodeType`, expecting a postal code; - `SlugType`, handle any `string` value to a slug; - `UnixTimestampType`, expecting an integer as UNIX timestamp; - `UrlType`, expecting an URL; - `UuidType`, expecting an UUID; - `Uuidv1Type`, expecting an UUIDv1; - `Uuidv3Type`, expecting an UUIDv3; - `Uuidv4Type`, expecting an UUIDv4; - `Uuidv5Type`, expecting an UUIDv5; - `VersionType`, expecting a version using Semantic Versioning; ### Masking Behavior [](#masking-behavior) Some **Advanced Objects** has the capability to mask its data: i.e. the `example@gmail.com` can be masked to `e******@g****.com` or `e*@g*.com`. Masked objects extends `AbstractMaskedType` and have two methods: - `isMasked() : bool`, returning if value is masked; - `masked( bool $keepLength = true ) : bool`, returning the masked value without mutate the original value. The `keepLength` as `true` will keep the value length as `e******@g****.com`, and as `false` will "compact" as `e*@g*.com`. *Mask a value will never mutate the value object*. It means if you have `new EmailType('example@gmail.com.br)` and want to persist the masked value or make only the masked value available you must: `new EmailType( $emailType->masked() );`. ### Password enhanced behavior [](#password-enhanced-behavior) #### Encryptation [](#encryptation) The `PasswordType` object has and enhanced behavior. When constructing it, the `constructor` will evaluate if password is encrypted with `password_hash()` native function or not. When not, it will encrypt following the options set with `PasswordType::hash()` static method. By default, encryptation will use the `\PASSWORD_BCRYPT` algorithm with default options. *After hashing, you will never ever get back the raw password*. But, you can always verify hash with the `check( $raw )` method. #### Strength [](#strength) Otherside, still in `constructor`, it will evaluate the password strengthness with the `PasswordStrengthLib` objects and throw an `InvalidValueTypeOfException` if password does not meet the minimum strength required. `PasswordStrengthLib` is an interface which implements: - `strength ( $raw )`, return an `integer` between 0 and 100 indicating the password strength. Or `false`, if password does not meet requirements; - `getMessage ()`, may return a `string` saying why password strength has failed. By default, there are three `libs` available in this library: - `PasswordBasicLib`, which implements the `zxcvbn` algo; - `PasswordCrackLib`, which uses the `cracklib-checker` command; - `PasswordPwScoreLib`, which uses the `pwscore` command. The `PasswordBasicLib` is applied by default to `PasswordType` object. Implementing all libs available increases the password strength checker accuracy. Custom Objects -------------- [](#custom-objects) You can create anytime custom objects always extending the `AbstractValueType` and preparing its own assertions. Samples ------- [](#samples) You can see very lightweight samples at [/samples](./samples) folder. Changelog --------- [](#changelog) See the [CHANGELOG](CHANGELOG.md) file for information about all code changes. Testing the code ---------------- [](#testing-the-code) This library uses the PHPUnit. We carry out tests of all the main classes of this application. ``` vendor/bin/phpunit ``` > You must always run tests with PHP 7.2 and greater. Contributions ------------- [](#contributions) See the [CONTRIBUTING](CONTRIBUTING.md) file for information before submitting your contribution. Credits ------- [](#credits) - [Caique Araujo](https://github.com/caiquearaujo) - [All contributors](../../contributors) Support the project ------------------- [](#support-the-project) Piggly Studio is an agency located in Rio de Janeiro, Brazil. If you like this library and want to support this job, be free to donate any value to BTC wallet `3DNssbspq7dURaVQH6yBoYwW3PhsNs8dnK` ❤. License ------- [](#license) MIT License (MIT). See [LICENSE](LICENSE). ### Health Score 25 — LowBetter than 37% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity58 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~124 days Total 2 Last Release 1670d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/8e37ceaff3cd04951d33004f062082f01b41c9b2adf5b2c241429bbf12362a5b?d=identicon)[piggly](/maintainers/piggly) --- Top Contributors [![caiquearaujo](https://avatars.githubusercontent.com/u/23598990?v=4)](https://github.com/caiquearaujo "caiquearaujo (9 commits)") --- Tags ormvalue objectsdata mapperpigglyvalue types ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/piggly-php-value-types/health.svg) ``` [![Health](https://phpackages.com/badges/piggly-php-value-types/health.svg)](https://phpackages.com/packages/piggly-php-value-types) ``` ### Alternatives [cycle/orm PHP DataMapper ORM and Data Modelling Engine 1.3k835.4k65](/packages/cycle-orm)[laravel-doctrine/migrations Doctrine Migrations for Laravel 782.8M16](/packages/laravel-doctrine-migrations)[laravel-doctrine/acl ACL for Laravel and Doctrine 44445.3k7](/packages/laravel-doctrine-acl)[laravel-doctrine/fluent A fluent PHP mapping driver for Doctrine2. 43430.3k13](/packages/laravel-doctrine-fluent)[wayofdev/laravel-cycle-orm-adapter 🔥 A Laravel adapter for CycleORM, providing seamless integration of the Cycle DataMapper ORM for advanced database handling and object mapping in PHP applications. 3516.7k3](/packages/wayofdev-laravel-cycle-orm-adapter)[opis/orm Powerful ORM library 335.4k1](/packages/opis-orm) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)