Skip to content

Commit

Permalink
Update the README
Browse files Browse the repository at this point in the history
- The simdjson PECL has cross-platform support.
  The support for Windows, MacOS, and Linux is implied by the
  installation instructions.
- Update simdjson json pointer $key examples to use standard syntax
  from the RFC with a leading slash ("/a/b").
  Note that releases < 4.0.0 required the non-RFC compliant "a/b"
  syntax due to a bug.
  • Loading branch information
TysonAndre committed Oct 23, 2022
1 parent 1a673da commit dbe045a
Show file tree
Hide file tree
Showing 3 changed files with 43 additions and 25 deletions.
28 changes: 15 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ simdjson_php bindings for the [simdjson project](https://github.com/lemire/simdj
[![Build Status (Windows)](https://ci.appveyor.com/api/projects/status/github/crazyxman/simdjson_php?svg=true)](https://ci.appveyor.com/project/crazyxman/simdjson-php)

## Requirement
- PHP 7 +
- We support platforms like Linux or macOS

- PHP 7.0+ (The latest php version was 8.2 at the time of writing)
- Prerequisites: g++ (version 7 or better) or clang++ (version 6 or better), and a 64-bit system with a command-line shell (e.g., Linux, macOS, freeBSD). We also support programming environments like Visual Studio and Xcode, but different steps are needed

## Installing
Expand Down Expand Up @@ -63,27 +63,28 @@ $jsonString = <<<'JSON'
}
JSON;

//Check if a JSON string is valid:
// Check if a JSON string is valid:
$isValid = simdjson_is_valid($jsonString); //return bool
var_dump($isValid); // true

//Parsing a JSON string. similar to the json_decode() function but without the fourth argument
// Parsing a JSON string. similar to the json_decode() function but without the fourth argument
try {
$parsedJSON = simdjson_decode($jsonString, true, 512); //return array|object|null. "null" string is not a standard json
var_dump($parsedJSON); // PHP array
} catch (RuntimeException $e) {
echo "Failed to parse $jsonString: {$e->getMessage()}\n";
}

//note. "/" is a separator. Can be used as the "key" of the object and the "index" of the array
//E.g. "Image/Thumbnail/Url" is ok.

// note. "/" is a separator. Can be used as the "key" of the object and the "index" of the array
// E.g. "/Image/Thumbnail/Url" is recommended starting in simdjson 4.0.0,
// but "Image/Thumbnail/Url" is accepted for now.

//get the value of a "key" in a json string
$value = simdjson_key_value($jsonString, "Image/Thumbnail/Url");
// get the value of a "key" in a json string
// (before simdjson 4.0.0, the recommended leading "/" had to be omitted)
$value = simdjson_key_value($jsonString, "/Image/Thumbnail/Url");
var_dump($value); // string(38) "http://www.example.com/image/481989943"

$value = simdjson_key_value($jsonString, "Image/IDs/4", true);
$value = simdjson_key_value($jsonString, "/Image/IDs/4", true);
var_dump($value);
/*
array(1) {
Expand All @@ -92,12 +93,13 @@ array(1) {
}
*/

//check if the key exists. return true|false|null. "true" exists, "false" does not exist, "null" string is not a standard json
$res = simdjson_key_exists($jsonString, "Image/IDs/1");
// check if the key exists. return true|false|null. "true" exists, "false" does not exist,
// throws for invalid JSON.
$res = simdjson_key_exists($jsonString, "/Image/IDs/1");
var_dump($res) //bool(true)

// count the values
$res = simdjson_key_count($jsonString, "Image/IDs");
$res = simdjson_key_count($jsonString, "/Image/IDs");
var_dump($res) //int(5)

```
Expand Down
35 changes: 25 additions & 10 deletions package.xml
Original file line number Diff line number Diff line change
Expand Up @@ -20,23 +20,16 @@
-->
<date>2022-10-19</date>
<version>
<release>4.0.0</release>
<api>4.0.0</api>
<release>4.0.1dev</release>
<api>4.0.1dev</api>
</version>
<stability>
<release>stable</release>
<api>stable</api>
</stability>
<license uri="https://www.apache.org/licenses/LICENSE-2.0.html">Apache 2.0</license>
<notes>
* Make the `SIMDJSON_ERR_*` constants case-sensitive in all PHP versions.
(The code it was based on was missing the flag needed to mark constants as case sensitive before PHP 8)
* Fix a bug that prevented using JSON pointer in `simdjson_key_count`, `simdjson_key_exists`, and `simdjson_key_value` with a leading slash https://www.rfc-editor.org/rfc/rfc6901.html.

This bug was introduced when working around test failures following a change in json pointer validation in the underlying C simdjson library.
* "" in a JSON pointer continues to refer to the entire document.
* "/" in a JSON pointer now properly refers to the key that is the empty string.
* Continue to allow the non-standard omission of the leading "/" for compatibility with earlier PECL releases. This may be deprecated in a subsequent release.
* Update the README
</notes>
<contents>
<dir name="/">
Expand Down Expand Up @@ -125,6 +118,28 @@
<providesextension>simdjson</providesextension>
<extsrcrelease/>
<changelog>
<release>
<date>2022-10-19</date>
<version>
<release>4.0.0</release>
<api>4.0.0</api>
</version>
<stability>
<release>stable</release>
<api>stable</api>
</stability>
<license uri="https://www.apache.org/licenses/LICENSE-2.0.html">Apache 2.0</license>
<notes>
* Make the `SIMDJSON_ERR_*` constants case-sensitive in all PHP versions.
(The code it was based on was missing the flag needed to mark constants as case sensitive before PHP 8)
* Fix a bug that prevented using JSON pointer in `simdjson_key_count`, `simdjson_key_exists`, and `simdjson_key_value` with a leading slash https://www.rfc-editor.org/rfc/rfc6901.html.

This bug was introduced when working around test failures following a change in json pointer validation in the underlying C simdjson library.
* "" in a JSON pointer continues to refer to the entire document.
* "/" in a JSON pointer now properly refers to the key that is the empty string.
* Continue to allow the non-standard omission of the leading "/" for compatibility with earlier PECL releases. This may be deprecated in a subsequent release.
</notes>
</release>
<release>
<version>
<release>3.0.0</release>
Expand Down
5 changes: 3 additions & 2 deletions php_simdjson.h
Original file line number Diff line number Diff line change
Expand Up @@ -51,12 +51,13 @@ BEGIN_EXTERN_C()
extern zend_module_entry simdjson_module_entry;
#define phpext_simdjson_ptr &simdjson_module_entry

#define PHP_SIMDJSON_VERSION "4.0.0"
#define PHP_SIMDJSON_VERSION "4.0.1dev"
/**
* PHP_SIMDJSON_VERSION_ID has the same format as PHP_VERSION_ID: Major version * 10000 + Minor version * 100 + Patch version.
* This is meant for use by PECL extensions that depend on simdjson.
* (e.g. 4.5.6dev and 4.5.6 would be 40506)
*/
#define PHP_SIMDJSON_VERSION_ID 40000
#define PHP_SIMDJSON_VERSION_ID 40001

#define SIMDJSON_SUPPORT_URL "https://github.com/crazyxman/simdjson_php"

Expand Down

0 comments on commit dbe045a

Please sign in to comment.