{"id":30662633,"url":"https://github.com/ryanwhitman/php-values","last_synced_at":"2026-03-06T22:09:10.295Z","repository":{"id":67780986,"uuid":"604207218","full_name":"ryanwhitman/php-values","owner":"ryanwhitman","description":"A tool for creating immutable value objects in PHP.","archived":false,"fork":false,"pushed_at":"2025-07-24T16:47:32.000Z","size":29,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-21T00:19:15.057Z","etag":null,"topics":["php","sanitation","validation","values"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ryanwhitman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-02-20T15:03:57.000Z","updated_at":"2025-07-24T16:47:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"680a23a6-0490-45bc-bddc-0f7cca6cd07e","html_url":"https://github.com/ryanwhitman/php-values","commit_stats":{"total_commits":19,"total_committers":1,"mean_commits":19.0,"dds":0.0,"last_synced_commit":"4ac3fce01049fce04ac559be3ce8cd5c8b7b8b3b"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ryanwhitman/php-values","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanwhitman%2Fphp-values","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanwhitman%2Fphp-values/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanwhitman%2Fphp-values/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanwhitman%2Fphp-values/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryanwhitman","download_url":"https://codeload.github.com/ryanwhitman/php-values/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryanwhitman%2Fphp-values/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30200756,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["php","sanitation","validation","values"],"created_at":"2025-08-31T16:49:47.826Z","updated_at":"2026-03-06T22:09:10.233Z","avatar_url":"https://github.com/ryanwhitman.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PHP Values\n\n[![Latest Version on Packagist][ico-version]][link-packagist] [![PHP from Packagist][ico-php-versions]][link-packagist] [![Software License][ico-license]](LICENSE) [![Total Downloads][ico-downloads]][link-packagist]\n\nPHP Values is a tool for creating immutable value objects in PHP. A value object intakes a raw value, transforms it, validates it, and can be used consistently and dependably across your application.\n\nFor instance, suppose you need an email address when creating a user. You can write it more traditionally like this:\n\n```php\npublic function createUser(string $email)\n{\n    // perform sanitation and validation on email before using\n}\n```\n\nBut it's more optimal to write it like this:\n\n```php\nuse RyanWhitman\\PhpValues\\Email;\n\npublic function createUser(Email $email)\n{\n    // email has already been sanitized and validated and is ready for use\n}\n```\n\n## Install\n\nYou should install the package via composer:\n\n```bash\ncomposer require ryanwhitman/php-values\n```\n\n## Example\n\nStart by creating a Value class. For instance, a Value class for an email address:\n\n```php\n\u003c?php\n\nnamespace App\\Values;\n\nuse RyanWhitman\\PhpValues\\Value;\nuse RyanWhitman\\PhpValues\\Concerns\\Stringable;\n\nclass Email extends Value\n{\n    use Stringable;\n\n    protected function transform(string $email): string\n    {\n        return filter_var($email, FILTER_SANITIZE_EMAIL);\n    }\n\n    protected function validate(string $email): bool\n    {\n        return filter_var($email, FILTER_VALIDATE_EMAIL);\n    }\n}\n```\n\nNow, you're ready to use the value:\n\n```php\n\u003c?php\n\nuse App\\Values\\Email;\n\n// Valid email address\nEmail::from('email@example.com'); // instance of Email\nEmail::from('email@example.com')-\u003eget(); // email@example.com\nEmail::getFrom('email@example.com'); // email@example.com\n(string) Email::from('email@example.com'); // email@example.com\nEmail::isValid('email@example.com'); // true\n\n// Valid email address (with imperfections)\nEmail::getFrom(' email @example.com '); // email@example.com\nEmail::isValid(' email @example.com '); // true\n\n// Invalid email address\nEmail::from('non-email'); // throws exception\nEmail::tryFrom('non-email'); // null\nEmail::isValid('non-email'); // false\n```\n\n## Usage\n\nTo create a new Value class, extend the `RyanWhitman\\PhpValues\\Value` class. From there, define a `transform` method (optional) and a `validate` method (mandatory). Upon instantiation, the `transform` method receives the raw input and transforms it, as needed. Then, the `validate` method receives the transformed value and returns `true` or `false`. If validation passes, the object is ready for use. If validation passes, `InvalidValueException` is thrown. Note: 2 `try` static methods exist that catch the exception and return `null`.\n\n#### transform(mixed $value): mixed\n\nThe `transform` method is an optional method called during instantiation. It receives the input value and, when defined, should return a sanitized/transformed version of the value. The transform method is not defined in the base abstract Value class to allow for proper typing in sub-classes.\n\n```php\nprotected function transform(string $email): string\n{\n    return filter_var($email, FILTER_SANITIZE_EMAIL);\n}\n```\n\n#### validate(mixed $value): bool\nThe `validate` method is called during instantiation. It receives the transformed value and should return true or false. The validate method is not defined in the base abstract Value class to allow for proper typing in sub-classes.\n\n```php\nprotected function validate(string $email): bool\n{\n    return filter_var($email, FILTER_VALIDATE_EMAIL);\n}\n```\n\n### Base Values\n\nSuppose you're creating a Value class for a person's name. You'll likely want to remove all superfluous whitespace. You could, of course, simply call another Value class within your `transform` method, but you can also define a `$baseValues` property to automatically run other Value classes:\n\n```php\n\u003c?php\n\nnamespace App\\Values;\n\nuse RyanWhitman\\PhpValues\\SquishedString;\nuse RyanWhitman\\PhpValues\\Value;\n\nclass Name extends Value\n{\n    protected array $baseValues = [\n        SquishedString::class,\n    ];\n\n    // ...\n}\n```\n\n### Static Methods\n\n#### from(mixed $value): Value\n\nThe `from` static method will return a Value instance when validation passes and will throw an exception when validation fails.\n\n```php\nEmail::from('email@example.com'); // instance of Email\nEmail::from('non-email'); // throws InvalidValueException\n```\n\n#### getFrom(mixed $value): mixed\n\nThe `getFrom` static method is a shortcut for `::from($value)-\u003eget()`.\n\n```php\nEmail::getFrom('email@example.com'); // email@example.com\nEmail::getFrom('non-email'); // throws InvalidValueException\n```\n\n#### tryFrom(mixed $value): ?Value\n\nThe `tryFrom` static method will return a Value instance when validation passes and `null` when validation fails.\n\n```php\nEmail::tryFrom('email@example.com'); // instance of Email\nEmail::tryFrom('non-email'); // null\n```\n\n#### tryGetFrom(mixed $value): mixed\n\nThe `tryGetFrom` static method is a shortcut for `::tryFrom($value)-\u003eget()`.\n\n```php\nEmail::tryGetFrom('email@example.com'); // email@example.com\nEmail::tryGetFrom('non-email'); // null\n```\n\n#### isValid(mixed $value): bool\n\nThe `isValid` static method will return true or false.\n\n```php\nEmail::isValid('email@example.com'); // true\nEmail::isValid('non-email'); // false\n```\n\n### Instance Methods\n\n#### getOrigValue(): mixed\n\nThe `getOrigValue` method returns the original input value (before transformation).\n\n```php\nEmail::from('e m ail@example.com')-\u003egetOrigValue(); // e m ail@example.com\n```\n\n#### get(): mixed\n\nThe `get` method returns the transformed and validated value.\n\n```php\nEmail::from('e m ail@example.com')-\u003eget(); // email@example.com\n```\n\n### Shortcut Methods\n\nAs mentioned above, the `getFrom` and `tryGetFrom` static methods are shortcuts for `::from($value)-\u003eget()` and `::tryFrom($value)-\u003eget()`, respectively. You may add the `ShortcutMethod` annotation/attribute to your custom get methods to add the same shortcut capabilities. Shortcut methods must be defined using camelCase and start with `get` (e.g. `getFormatted`).\n\nUsing a [doctrine annotation](https://www.doctrine-project.org/projects/doctrine-annotations/en/2.0/index.html) in PHP 7.4+:\n\n```php\nuse RyanWhitman\\PhpValues\\Annotations\\ShortcutMethod;\n\n/**\n * @ShortcutMethod\n */\npublic function getFormatted()\n{\n    // ...\n}\n```\n\nUsing an [attribute](https://www.php.net/manual/en/language.attributes.overview.php) in PHP 8.0+:\n\n```php\nuse RyanWhitman\\PhpValues\\Attributes\\ShortcutMethod;\n\n#[ShortcutMethod]\npublic function getFormatted()\n{\n    // ...\n}\n```\n\nAfter adding the `ShortcutMethod` annotation/attribute to the `getFormatted` method, for example, the following will work:\n\n```php\n::getFormattedFrom($value)\n::tryGetFormattedFrom($value)\n```\n\n### Traits\n\n#### RyanWhitman\\PhpValues\\Concerns\\Stringable\n\nThe `Stringable` trait simply defines the `__toString()` magic method with `(string) $this-\u003eget()`.\n\n### Exceptions\n\nPHP Values will throw 1 of 2 exceptions:\n\n`RyanWhitman\\PhpValues\\Exceptions\\InvalidValueException` will be thrown when either a `TypeError` occurs (e.g. an array is needed but a string is provided) or when validation fails. This exception is useful as it indicates the raw input is invalid. `RyanWhitman\\PhpValues\\Exceptions\\Exception` is thrown when something else goes wrong (e.g. a `validate` method is not defined). Note: The `try` methods only catch `InvalidValueException`.\n\n## Pre-Built Values\n\n- [Email](https://github.com/RyanWhitman/php-values/blob/main/src/Email.php)\n- [SquishedString](https://github.com/RyanWhitman/php-values/blob/main/src/SquishedString.php)\n- [TrimmedString](https://github.com/RyanWhitman/php-values/blob/main/src/TrimmedString.php)\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n## Security\n\nIf you discover any security-related issues, please email [ryanawhitman@gmail.com](mailto:ryanawhitman@gmail.com) instead of using the issue tracker.\n\n## Credits\n\n- [Ryan Whitman][link-author]\n- [All Contributors][link-contributors]\n\n## License\n\nThe MIT License (MIT). Please have a look at [License File](LICENSE) for more information.\n\n[ico-version]: https://img.shields.io/packagist/v/ryanwhitman/php-values.svg?style=flat-square\n[ico-php-versions]: https://img.shields.io/packagist/php-v/ryanwhitman/php-values?style=flat-square\n[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square\n[ico-downloads]: https://img.shields.io/packagist/dt/ryanwhitman/php-values.svg?style=flat-square\n\n[link-packagist]: https://packagist.org/packages/ryanwhitman/php-values\n[link-author]: https://github.com/RyanWhitman\n[link-contributors]: ../../contributors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryanwhitman%2Fphp-values","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryanwhitman%2Fphp-values","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryanwhitman%2Fphp-values/lists"}