Download the PHP package sandermuller/json without Composer
On this page you can find all versions of the php package sandermuller/json. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download sandermuller/json
More information about sandermuller/json
Files in sandermuller/json
Package json
Short Description Typed JSON encoding and decoding for PHP with strict error handling and shape assertions.
License MIT
Homepage https://github.com/sandermuller/json
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package json
Json
Typed JSON encoding and decoding for PHP with strict error handling and shape assertions.
json_decode() returns mixed, so every caller writes the same is_array() guard by hand or lies to the type system with a docblock. This package does the guard once and gives you a return type your static analyser can use.
It also replaces GuzzleHttp\Utils::jsonDecode() and GuzzleHttp\Utils::jsonEncode(), deprecated in guzzle 7.15 and removed in 8.0.
Installation
Requires PHP 8.3+. No runtime dependencies.
Usage
Every method throws on malformed input, so there is no silent false or null to forget to check. The two methods that can return null say so in their names.
Shapes
Each shape method decodes and asserts, so the return type is narrow:
Json::list() is the useful one under PHPStan: json_decode($json, true) gives you array, which is not a list, so a @return list<T> signature forces a redundant array_values(). Json::list() returns list<mixed> directly.
When a wrong shape is expected
Sometimes the JSON parses fine but holds the wrong shape, and that is a case you handle locally. arrayOrNull() and objectOrNull() relax the shape check and leave everything else alone:
A JSON null comes back as null too, the same as any other shape that is not the one you asked for.
Normalising a value
Json::normalize() deep-converts a value into plain nested arrays by round-tripping it through JSON. It replaces the Json::array(Json::encode($value)) idiom:
JSON's own rules apply: only public properties survive, and INF, NAN, resources, and malformed UTF-8 all throw. A value that does not encode to an object or array is a shape failure, exactly as it would be through Json::array(). normalizeNullable() excuses a null input; everything else still fails.
Both methods run at the default depth and accept no flags. Anything Json::encode() can represent survives the round trip, since the decode leg gets one extra level (decoding [[[1]]] needs 4 where encoding it needs 3). For control over flags or depth, do the round trip by hand with Json::encode() and Json::array().
Errors
A shape mismatch throws UnexpectedJsonShapeException, which extends the native JsonException. One catch covers both malformed JSON and an unexpected shape:
Passing an unsupported flag throws UnsupportedJsonFlagException, which extends InvalidArgumentException rather than JsonException: it means the call is wrong, not the data.
The reported type is the type the JSON decoded to, which a flag can shift: Json::int('9223372036854775808', JSON_BIGINT_AS_STRING) reports got string even though the JSON held an integer.
Flags and depth
Both are passthroughs, positioned so the common case stays short. JSON_THROW_ON_ERROR is always added on top of whatever you pass:
Two flags throw UnsupportedJsonFlagException instead of being honoured:
| Flag | Why |
|---|---|
JSON_PARTIAL_OUTPUT_ON_ERROR (encode) |
Suppresses JSON_THROW_ON_ERROR, returning a string with unencodable values replaced by null. |
JSON_OBJECT_AS_ARRAY (decode) |
Each method fixes its own object representation, so the flag could only ever be discarded. |
$depth below 1 is a programming error. Encode throws JsonException and decode throws ValueError, matching PHP's own behaviour in each case.
Replacing GuzzleHttp\Utils
| Deprecated | Replacement |
|---|---|
Utils::jsonEncode($v) |
Json::encode($v) |
Utils::jsonEncode($v, $flags) |
Json::encode($v, $flags) |
Utils::jsonDecode($j) |
Json::decode($j), or Json::object($j) when it is always an object |
Utils::jsonDecode($j, true) |
Json::array($j) |
Two differences to port carefully:
The second argument changed meaning. Guzzle's was bool $assoc; here it is int $flags. Json::decode($json, true) is therefore not the port of Utils::jsonDecode($json, true); use Json::array($json). From a caller without declare(strict_types=1), that true would otherwise coerce to 1 (JSON_OBJECT_AS_ARRAY) and quietly hand back a stdClass. That exact flag is rejected with an error message naming the correct replacement, so the mistake fails loudly instead.
The exception type changed. Guzzle threw GuzzleHttp\Exception\InvalidArgumentException (an SPL InvalidArgumentException); this package throws JsonException. Update catch blocks accordingly.
Testing
Changelog
CHANGELOG.md has the release history. PUBLIC_API.md lists the semver-protected surface, so you can tell which changes are breaking.
License
MIT. See LICENSE.
