{"id":28418716,"url":"https://github.com/facile-it/php-codec","last_synced_at":"2025-07-03T20:35:11.707Z","repository":{"id":44950451,"uuid":"350761571","full_name":"facile-it/php-codec","owner":"facile-it","description":"A partial porting of io-ts in PHP.","archived":false,"fork":false,"pushed_at":"2025-05-30T06:41:20.000Z","size":275,"stargazers_count":10,"open_issues_count":12,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-30T07:59:46.022Z","etag":null,"topics":["decoder","io-ts","php"],"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/facile-it.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2021-03-23T15:23:54.000Z","updated_at":"2024-07-12T10:45:12.000Z","dependencies_parsed_at":"2024-01-25T07:23:29.824Z","dependency_job_id":"83f72b1a-80e4-4640-8916-bfdf47463500","html_url":"https://github.com/facile-it/php-codec","commit_stats":{"total_commits":41,"total_committers":8,"mean_commits":5.125,"dds":"0.41463414634146345","last_synced_commit":"9cd82db7b722d5b44985156ebcb5f094f154b560"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/facile-it/php-codec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facile-it%2Fphp-codec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facile-it%2Fphp-codec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facile-it%2Fphp-codec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facile-it%2Fphp-codec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facile-it","download_url":"https://codeload.github.com/facile-it/php-codec/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facile-it%2Fphp-codec/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262375584,"owners_count":23301310,"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":["decoder","io-ts","php"],"created_at":"2025-06-04T12:20:06.930Z","updated_at":"2025-07-03T20:35:11.692Z","avatar_url":"https://github.com/facile-it.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PHP-codec\nPHP-codec is a partial porting of [io-ts](https://github.com/gcanti/io-ts) in PHP.\n\n[![Minimum PHP Version](https://img.shields.io/badge/php-%3E%3D%207.4-8892BF.svg)](https://php.net/)\n\n[![CI](https://github.com/facile-it/php-codec/actions/workflows/ci.yaml/badge.svg?branch=master\u0026event=push)](https://github.com/facile-it/php-codec/actions/workflows/ci.yaml)\n[![Static analysis](https://github.com/facile-it/php-codec/actions/workflows/static-analysis.yaml/badge.svg?branch=master\u0026event=push)](https://github.com/facile-it/php-codec/actions/workflows/static-analysis.yaml)\n[![codecov](https://codecov.io/gh/facile-it/php-codec/branch/master/graph/badge.svg?token=HP4OFEEPY6)](https://codecov.io/gh/facile-it/php-codec) [![Join the chat at https://gitter.im/php-codec/community](https://badges.gitter.im/php-codec/community.svg)](https://gitter.im/php-codec/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nInstall it now. It only requires PHP \u003e= 7.4.\n    \n    composer require facile-it/php-codec\n\n# Disclaimer\n\nThis project is under active development: it's unstable and still poorly documented.\nThe API is likely to change several times, and it won't be ready for production soon.\n\nThe project follows [semantic versioning](https://semver.org/).\n\n# Introduction\n\nThis project is a partial porting of the fantastic [io-ts](https://github.com/gcanti/io-ts) library for Typescript.\nEverything rounds about the concept of decoder, encoder and codec.\n\nDecoders are capable of transform values from one type to another one. This transformation may fail.\n\n```php\nuse Facile\\PhpCodec\\Validation\\Validation;\n\n/**\n * @psalm-template I\n * @psalm-template A\n */\ninterface Decoder {\n     /**\n     * @psalm-param I $i\n     * @psalm-return Validation\u003cA\u003e\n     */\n    public function decode($i): Validation;\n    \n    /** ... */\n}\n```\n\nEncoders do a similar transformation but between types such that it cannot fail.\n\n```php\n/**\n * @psalm-template A\n * @psalm-template O\n */\ninterface Encoder\n{\n    /**\n     * @psalm-param A $a\n     * @psalm-return O\n     */\n    public function encode($a);\n}\n```\n\nCodecs are a combination of a decoder and an encoder, putting together their features.\n\nI recommend reading the [The Idea](https://github.com/gcanti/io-ts/blob/master/index.md#the-idea) section from the \ndocumentation of io-ts. It starts with a beautiful description of what codecs are.\n\u003e A value of type `Type\u003cA, O, I\u003e` (called \"codec\") is the run time representation of the static type `A`.\n\n# Getting started\n\n    composer require facile-it/php-codec\n\n## Decoders\n\nDecoders are objects with decoding capabilities.\nA decoder of type `Decoder\u003cI, A\u003e` takes an input of type `I` and builds a result of type `Validation\u003cA\u003e`.\n\nThe class `Facile\\PhpCodec\\Decoders` provides factory methods for built-in decoders and combinators.\n\n### How to use decoders\n\n```php\nuse Facile\\PhpCodec\\Decoders;\nuse Facile\\PhpCodec\\Decoder;\nuse Facile\\PhpCodec\\Validation\\Validation;\nuse Facile\\PhpCodec\\Validation\\ValidationFailures;\nuse Facile\\PhpCodec\\Validation\\ValidationSuccess;\n\n/** @var Decoder\u003cstring, int\u003e $decoder */\n$decoder = Decoders::intFromString();\n\n/** @var Validation\u003cint\u003e $v1 */\n$v1 = $decoder-\u003edecode('123');\n// Since '123' is a numeric string which represents an integer,\n// then we can expect the decoding to be successful.\n// Hence, $v1 will be an instance of ValidationSuccess\n\nif($v1 instanceof ValidationSuccess) {\n    var_dump($v1-\u003egetValue());\n}\n\n/** @var Validation\u003cint\u003e $v2 */\n$v2 = $decoder-\u003edecode('hello');\n// Similarly, since 'hello' is not a numeric string, we expect \n// the decoding fail. $v2 will be an instance of ValidationError\n\nif($v2 instanceof ValidationFailures) {\n    var_dump($v2-\u003egetErrors());\n}\n```\n\n### Dealing with the validation result\n\nWe can use `Validation::fold` to destruct the validation result while providing \na valid result in any case. \n\n```php\nuse Facile\\PhpCodec\\Decoders;\nuse Facile\\PhpCodec\\Decoder;\nuse Facile\\PhpCodec\\Validation\\Validation;\n\n/** @var Decoder\u003cstring, int\u003e $decoder */\n$decoder = Decoders::intFromString();\n\nValidation::fold(\n    function (\\Facile\\PhpCodec\\Validation\\ValidationFailures $failures): int {\n        // I may not care about the error.\n        // Here I want to give a default value when the deconding fails.\n        return 0;\n    },\n    function (\\Facile\\PhpCodec\\Validation\\ValidationSuccess $success): int {\n        return $success-\u003egetValue();\n    },\n    $decoder-\u003edecode($input)\n);\n```\n\nYou can use the path reporter to build well-formatted error messages for failures.\n\n```php\nuse Facile\\PhpCodec\\Decoders;\n\n$decoder = Decoders::intFromString();\n$v = $decoder-\u003edecode('hello');\n$msgs = \\Facile\\PhpCodec\\Reporters::path()-\u003ereport($v);\n\nvar_dump($msgs);\n/* This will print \narray(1) {\n  [0] =\u003e\n  string(49) \"Invalid value \"hello\" supplied to : IntFromString\"\n}\n*/\n```\n\n## Examples\n\nTake a look to the [examples](https://github.com/facile-it/php-codec/tree/master/tests/examples) folder.\n\n\n# Reporters\n\nReporters do create reports from `Validation` objects.\nGenerally speaking, reporters are objects that implement the `Reporter\u003cT\u003e` interface, given `T` the type of the report that the generate.\n\nOne interesting group of reporters is the validation error reporters group.\nThey implements `Reporter\u003clist\u003cstring\u003e\u003e`.\nThus, given a `Validation` object, they generate a list of error messages for each validation error.\n\nPHP-Codec comes with two error reporters:\n\n- PathReporter, which is a pretty straightforward porting of io-ts' [PathReporter](https://github.com/gcanti/io-ts/blob/master/index.md#error-reporters).\n- SimplePathReporter, which is a simplified (read: shorter messages) version of the PathReporter.\n\n```php\n$d = Decoders::arrayProps([\n  'a' =\u003e Decoders::arrayProps([\n    'a1' =\u003e Decoders::int(),\n    'a2' =\u003e Decoders::string(),\n  ]),\n  'b' =\u003e Decoders::arrayProps(['b1' =\u003e Decoders::bool()])\n]);\n$v = $d-\u003edecode(['a'=\u003e ['a1' =\u003e 'str', 'a2' =\u003e 1], 'b' =\u003e 2]);\n\n$x = \\Facile\\PhpCodec\\Reporters::path()-\u003ereport($v);\n// $x will be\n// ['Invalid value \"str\" supplied to : {a: {a1: int, a2: string}, b: {b1: bool}}/a: {a1: int, a2: string}/a1: int',\n//  'Invalid value 1 supplied to : {a: {a1: int, a2: string}, b: {b1: bool}}/a: {a1: int, a2: string}/a2: string',\n//  'Invalid value undefined supplied to : {a: {a1: int, a2: string}, b: {b1: bool}}/b: {b1: bool}/b1: bool']\n\n$y = \\Facile\\PhpCodec\\Reporters::simplePath()-\u003ereport($v);\n// $y will be\n// ['/a/a1: Invalid value \"str\" supplied to decoder \"int\"',\n//  '/a/a2: Invalid value 1 supplied to decoder \"string\"',\n//  '/b/b1: Invalid value undefined supplied to decoder \"bool\"']\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacile-it%2Fphp-codec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacile-it%2Fphp-codec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacile-it%2Fphp-codec/lists"}