Skip to content

Commit

Permalink
Added missing files required to satisfy Module Standard 1.0
Browse files Browse the repository at this point in the history
Update README accordingly.
  • Loading branch information
phptek committed Jun 14, 2016
1 parent dacd106 commit 9a508f8
Show file tree
Hide file tree
Showing 6 changed files with 69 additions and 20 deletions.
4 changes: 4 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/tests export-ignore
/.gitignore export-ignore
/.travis.yml export-ignore
/.scrutinuzer.yml export-ignore
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Nothing's changed yet.
47 changes: 33 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,30 @@
[![Build Status](https://api.travis-ci.org/phptek/silverstripe-jsontext.svg?branch=master)](https://travis-ci.org/phptek/silverstripe-jsontext)
[![License](https://poser.pugx.org/phptek/jsontext/license.svg)](https://github.com/phptek/silverstripe-jsontext/blob/master/LICENSE.md)

This module does pretty much does what it says on the tin: Provides a simple Text field into
which JSON can be stored and from which it can be queried.
JSON storage and querying.

Once stored, the module exposes a simple query API based on the [JSON operators found in Postgres v9.2+](https://www.postgresql.org/docs/9.5/static/functions-json.html),
## Requirements

PHP 5.4+
SilverStripe Framework 3.1+
SilverStripe CMS 3.1+

## Introduction

The module exposes a simple query API based on the [JSON operators found in Postgres v9.2+](https://www.postgresql.org/docs/9.5/static/functions-json.html),
but with some modifications:

In Postgres both the `->` and `->>` operators act as string and integer key matchers on a JSON array or object. The module
however treats both source types the same - they are after all *both JSON* so `->` is used as an **Integer Matcher** and `->>` as a string matcher
*regardless* of the "type" of JSON stored.
In Postgres both the `->` and `->>` operators act as string and integer key matchers on a JSON array or object respectively. The module
however treats both source types the same - they are after all *both JSON* so `->` is used as an **Integer Matcher** and `->>` as a **String Matcher**
*regardless* of the "type" of source JSON stored.

In Postgress the `#>` path match operator can act as an object or a text matcher, but again, the module wishes to simplify things and as such
In Postgress the `#>` path match operator can act as an object or a text matcher, but the module wishes to simplify things and as such
the `#>` operator is *just a simple path matcher*.

I see nothing but confusion if the same operator were to be treated differently
depending on the format of the source data but am prepared for discussion on it if any were forthcoming.
I see nothing but confusion arising if the same operator were to be treated differently
depending on the specific *type of JSON* stored.

I'm a reasonable man however, and am prepared for a discussion on it, if any were to be forthcoming.

Note: This module's query API is based on a relatively simple JSON to array conversion principle.
It does *not* use Postgres' or MySQL's JSON operators at the ORM level. The aim however
Expand All @@ -32,22 +41,32 @@ JSONText:
Note: The module default is to use `postgres` which is also the only backend that will work at the moment.

# Stability
## Installation

```bash
#> composer require phptek/silverstripe-jsontext
```

## Stability

This is currently *alpha software*. At time of writing (June 2016) there is
support for the `->` (Int matcher), `->>` (String matcher) and `#>` (Path matcher) operators and although well-tested,
they are far from complete.

This leads me to..

# Contributing
## Contributing

If you've been using Postgres or MySQL with its JSON functions for some time,
I'm keen to hear from you. Some simple failing tests would be most welcome.

See: [CONTRIBUTING.md](CONTRIBUTING.md)

# Usage
## Reporting an issue

I shouldn't need to tell you what I need in a bug report. If it were *your module*, what would you need to know? :-)

## Usage

The module can be put into `mysql` or `postgres` query mode using SS config thus:

Expand Down Expand Up @@ -135,10 +154,10 @@ In the examples below, if you pass invalid queries or malformed JSON (where appl
}
```

# TODO
## TODO

* Lose the fugly way that data is queried via `$this->dbObject()`

# Author
## Author

Russell Michell 2016 <[email protected]>
1 change: 1 addition & 0 deletions code/models/fieldtypes/JSONText.php
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
* @subpackage fields
* @author Russell Michell <[email protected]>
* @todo Make the current default of "strict mode" into ss config and default to strict.
* @todo Add tests for "minimal" yet valid JSON types e.g. `true`
*/

namespace JSONText\Fields;
Expand Down
16 changes: 11 additions & 5 deletions composer.json
Original file line number Diff line number Diff line change
@@ -1,19 +1,25 @@
{
"name": "phptek/jsontext",
"type": "silverstripe-module",
"description": "JSON storage and querying",
"homepage": "http://theruss.com/",
"license": "BSD",
"type": "silverstripe-module",
"keywords": ["silverstripe", "JSON", "json", "Field", "Query"],
"license": "BSD",
"authors": [
{
"name": "Russell Michell",
"homepage": "http://theruss.com",
"email": "[email protected]"
}
],
"require": {
"php": ">=5.4,<7",
"silverstripe/framework": ">=3.1",
"silverstripe/cms": ">=3.1"
"silverstripe/framework": "~3.1",
"silverstripe/cms": "~3.1"
},
"support": {
"issues": "https://github.com/phptek/silverstripe-jsontext/issues"
},
"extra": {
"installer-name": "jsontext"
}
}
20 changes: 19 additions & 1 deletion tests/JSONTextTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ class JSONTextTest extends SapphireTest
'invalid' => 'tests/fixtures/json/invalid.json',
'hash_deep' => 'tests/fixtures/json/hash_deep.json',
'hash_dupes' => 'tests/fixtures/json/hash_duplicated.json',
'empty' => 'tests/fixtures/json/empty.json'
'empty' => 'tests/fixtures/json/empty.json',
'minimal_bool' => 'tests/fixtures/json/minimal_bool.json'
];

/**
Expand Down Expand Up @@ -272,6 +273,23 @@ public function testQuery_MatchPathDuplicate_AsArray()
$field->setReturnType('array');

$this->assertEquals([["Subaru" => "Impreza"],["Kawasaki" => "KR1S250"]], $field->query('#>', '{"japanese":"fast"}'));
$this->assertEquals([], $field->query('#>', '{"":"fast"}')); // No match
$this->setExpectedException('\JSONText\Exceptions\JSONTextException');
$this->assertEquals([], $field->query('#>', 1)); // Bad matcher used
}

/**
* Tests query() by means of path-matching using the Postgres path match operator: '#>' but where duplicate keys exist
* for different parent structures in the source data
*/
public function testQuery_MatchPathDuplicate_AsJSON()
{
// Hashed
$field = JSONText\Fields\JSONText::create('MyJSON');
$field->setValue($this->getFixture('hash_dupes'));
$field->setReturnType('json');

$this->assertEquals('[{"Subaru":"Impreza"},{"Kawasaki":"KR1S250"}]', $field->query('#>', '{"japanese":"fast"}'));
}

/**
Expand Down

0 comments on commit 9a508f8

Please sign in to comment.