{"id":20330547,"url":"https://github.com/mle86/php-value","last_synced_at":"2025-03-04T12:37:51.079Z","repository":{"id":57018166,"uuid":"41364074","full_name":"mle86/php-value","owner":"mle86","description":"PHP Immutable Value Object base class","archived":false,"fork":false,"pushed_at":"2021-12-21T09:04:28.000Z","size":91,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-16T19:02:34.719Z","etag":null,"topics":["base-class","immutable-objects","immutable-values","php","php-library","php7"],"latest_commit_sha":null,"homepage":null,"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/mle86.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-25T13:12:29.000Z","updated_at":"2022-02-12T13:43:59.000Z","dependencies_parsed_at":"2022-08-22T11:31:17.962Z","dependency_job_id":null,"html_url":"https://github.com/mle86/php-value","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mle86%2Fphp-value","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mle86%2Fphp-value/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mle86%2Fphp-value/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mle86%2Fphp-value/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mle86","download_url":"https://codeload.github.com/mle86/php-value/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241851233,"owners_count":20030961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["base-class","immutable-objects","immutable-values","php","php-library","php7"],"created_at":"2024-11-14T20:16:38.339Z","updated_at":"2025-03-04T12:37:51.057Z","avatar_url":"https://github.com/mle86.png","language":"PHP","readme":"# php-value\n\n[![Build Status](https://travis-ci.org/mle86/php-value.svg?branch=master)](https://travis-ci.org/mle86/php-value)\n[![Coverage Status](https://coveralls.io/repos/github/mle86/php-value/badge.svg?branch=master)](https://coveralls.io/github/mle86/php-value?branch=master)\n[![Latest Stable Version](https://poser.pugx.org/mle86/value/version)](https://packagist.org/packages/mle86/value)\n[![PHP 7.0](https://img.shields.io/badge/php-7.0-8892BF.svg?style=flat)](https://php.net/)\n[![License](https://poser.pugx.org/mle86/value/license)](https://packagist.org/packages/mle86/value)\n\nThis PHP library provides a simple base class for Immutable Value Objects.\nThose are objects which wrap exactly one value,\ncannot be changed in any way,\nhave no additional state,\nand carry some validation logic in the constructor.\n\nIt is released under the [MIT License](http://opensource.org/licenses/MIT).\n\n\n# Simple use case:\n\n```php\nclass OddNumber extends \\mle86\\Value\\AbstractValue\n{\n\n    // The base class requires this boolean test method:\n    public static function isValid($input): bool\n    {\n        return (is_int($input) \u0026\u0026 ($input % 2) === 1);\n    }\n\n    // Nothing else is needed.\n}\n\nfunction myFunction(OddNumber $oddArgument)\n{\n    /* No further validation of $oddArgument is necessary in this function,\n     * it's guaranteed to contain an odd number. */\n    print \"Got an odd number here: \" . $oddArgument-\u003evalue();\n}\n\n$odd1 = new OddNumber(61);       // works as expected, $odd1-\u003evalue() will return 61\n$odd2 = new OddNumber(40);       // throws an InvalidArgumentException\n$odd3 = new OddNumber(\"string\"); // throws an InvalidArgumentException\n$odd4 = new OddNumber(null);     // throws an InvalidArgumentException\n\n$odd5   = OddNumber::optional(33);   // works as expected, $odd5-\u003evalue() will return 33\n$nonodd = OddNumber::optional(null); // $nonodd is now null\n$odd6   = OddNumber::optional(40);   // throws an InvalidArgumentException\n```\n\n\n# Installation:\n\nVia Composer:  `composer require mle86/value`\n\nOr insert this into your project's `composer.json` file:\n\n```json\n\"require\": {\n    \"mle86/value\": \"^2\"\n}\n```\n\n\n# Minimum PHP version:\n\nPHP 7.0\n\n\n# Classes and interfaces:\n\n1. [Value](#value) (interface)\n1. [AbstractValue](#abstractvalue)  (abstract class)\n1. [AbstractSerializableValue](#abstractserializablevalue)  (abstract class)\n1. [InvalidArgumentException](#invalidargumentexception)  (exception)\n1. [NotImplementedException](#notimplementedexception)  (exception)\n\n\n## Value\n\nThis interface specifies that all Value classes should have\n* a constructor which takes exactly one argument,\n* a value() method without arguments.\n\n\n## AbstractValue\n\nThis immutable class wraps a single value per instance.\nThe constructor enforces validity checks on the input value.\nTherefore, every class instance's wrapped value can be considered valid.\n\nThe validity checks are located in the isValid class method which all\nsubclasses must implement.  It is a class method to allow validity checks\nof external values without wrapping them in an instance.\n\n\n* \u003ccode\u003epublic function \u003cb\u003e\\_\\_construct\u003c/b\u003e($rawValue)\u003c/code\u003e\n\n  The constructor uses the `isValid` class method to test its input argument.\n  Valid values are stored in the new instance, invalid values cause an `InvalidArgumentException` to be thrown.\n  Other instances of the same class are always considered valid (*re-wrapping*).\n\n* \u003ccode\u003epublic static function \u003cb\u003eoptional\u003c/b\u003e($rawValue): ?static\u003c/code\u003e\n\n  Same as the default constructor,\n  but also accepts `null` values (which will be returned unchanged).\n\n* \u003ccode\u003eabstract public static function \u003cb\u003eisValid\u003c/b\u003e($testValue): bool\u003c/code\u003e\n\n  Checks the validity of a raw value.\n  If it returns true, a new object can be instantiated with that value.\n  Implement this in every subclass!\n\n* \u003ccode\u003efinal public function \u003cb\u003evalue\u003c/b\u003e(): mixed\u003c/code\u003e\n\n  Returns the object's wrapped initializer value.\n\n* \u003ccode\u003efinal public function \u003cb\u003eequals\u003c/b\u003e($testValue): bool\u003c/code\u003e\n\n  Equality test.\n  This method performs an equality check on other instances or raw values.\n  Objects are considered equal if and only if they are instances of the same subclass and carry the same `value()`.\n  All other values are considered equal if and only if they are identical (`===`) to the current objects's `value()`.\n\n* \u003ccode\u003efinal public static function \u003cb\u003ewrap\u003c/b\u003e(\u0026$value)\u003c/code\u003e\n\n  Replaces a value (by-reference) with instance wrapping that value.\n  This means of course that the call will fail with an `InvalidArgumentException` if the input value fails the subclass' `isValid` check.\n  If the value already is an instance, it won't be replaced.\n\n* \u003ccode\u003efinal public static function \u003cb\u003ewrapOptional\u003c/b\u003e(\u0026$value)\u003c/code\u003e\n\n  Like `wrap()`, but won't change `null` values.\n\n* \u003ccode\u003efinal public static function \u003cb\u003ewrapArray\u003c/b\u003e(array \u0026$array): array\u003c/code\u003e\n\n  Will replace all values in an array with instances.\n  The array will only be altered (by-reference) if all its values are valid.\n  Array keys will be preserved.\n\n* \u003ccode\u003efinal public static function \u003cb\u003ewrapOptionalsArray\u003c/b\u003e(array \u0026$array): array\u003c/code\u003e\n\n  Will replace all non-`null` values in an array with instances.\n  The array will only be changed (by-reference) if all its values are valid (or `null`).\n  Array keys will be preserved.\n\n\n## AbstractSerializableValue\n\nThis extension of `AbstractValue` provides easy serializability for the Value objects.\nIt implements the [JsonSerializable](https://php.net/manual/class.jsonserializable.php) interface.\n\nStandard PHP serialization via [serialize](https://secure.php.net/serialize)/[unserialize](https://secure.php.net/unserialize)\nis always supported.\nThis class contains an extra `__wakeup()` implementation\nto make sure that unserialized instances always contain a valid value.\n\n* \u003ccode\u003epublic function \u003cb\u003e\\_\\_toString\u003c/b\u003e(): string\u003c/code\u003e\n\n  Returns the wrapped value like `value()`, but with an explicit\n  `string` typecast.  This allows string concatenation of Value objects.\n\n* \u003ccode\u003epublic function \u003cb\u003ejsonSerialize\u003c/b\u003e(): mixed\u003c/code\u003e\n\n  Returns the wrapped value –\n  like `value()`.\n  This enables [json\\_encode()](https://secure.php.net/json_encode) to encode the object.\n\n\n## InvalidArgumentException\n\nAn empty extension of PHP's `InvalidArgumentException`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmle86%2Fphp-value","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmle86%2Fphp-value","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmle86%2Fphp-value/lists"}