tmilos / scim-filter-parser

SCIM AST filter parser PHP library

SCIM filter parser

The PHP parser for SCIM filter. SCIM stands for System for Cross-domain Identity Management and more details can be found on http://www.simplecloud.info/ website.

Usage

Filter mode

<?php
$parser = new Parser(Mode::FILTER());
$node = $parser->parse('userType eq "Employee" and (emails co "example.com" or emails.value co "example.org")');
/*
walk the node...

Conjunction = {
    ComparisonExpression => userType eq Employee
    Disjunction => {
        ComparisonExpression => emails co example.com
        ComparisonExpression => emails.value co example.org
    }
}
*/

Path mode

<?php
$parser = new Parser(Mode::PATH());
$node = $parser->parse('members[value eq "2819c223-7f76-453a-919d-413861904646"].displayName');
/*
walk the node...

Path = {
    ValuePath = {
        AttributePath = 'members'
        ComparisonExpression = value eq 2819c223-7f76-453a-919d-413861904646
    }
    AttributePath = displayName,
}
*/

For more details look at the filter mode and path mode unit tests.

Filter and path mode

SCIM v2 for PATCH operations defines parsable path with different grammar than for the retrieving resources filter expressions. The parser by default is in the FILTER mode, but you can switch it to PATH mode either with optional constructor argument or with a Parser::setMode(Mode $mode) setter method.

Note: Path mode is valid only for SCIM v2 version.

<?php
$parser = new Parser(Mode::PATH());
$parser->parse('username'); // OK
$parser->parse('username eq "xxx"'); // throws ParseException - Col 8: Expected end of input, but got ' '

SCIM filter version

SCIM filter between versions v1 and v2 remained almost the same, with the difference that v2 introduced new ValuePath syntax. Parser is by default in v2 mode, and you can switch it to v1 with Parser::setVersion(Version::V1()) setter or with optional constructor argument. In v1 mode it will throw syntax errors when brackets are encountered.

<?php
$parser = new Parser(Mode::FILTER, Version::V1());
$parser->parse('emails[type eq "work"]'); // throws ParseException - Col 6: Expected SP, got '['

scim-filter-parser's Issues

Unexpected exception thrown for valid filter

Using https://scimvalidator.microsoft.com/, a filter request was sent with the following filter which throws an Exception

emails[type eq "work"].value eq "[email protected]"

I would assume the above filter is valid however the parser is unable to handle this.

(new Parser(Mode::FILTER()))->parse('emails[type eq "work"].value eq "[email protected]"')

Request
GET /scim/v2/Users?filter=filter=emails%5Btype%20eq%20%22work%22%5D.value%20eq%20%22gerson_nader%40strosin.us%22

Exception

[Tmilos\ScimFilterParser\Error\FilterException](file:///REDACTED/vendor/tmilos/scim-filter-parser/src/Error/FilterException.php#L14) {#3097 ▼
    #message: "[Syntax Error] line 0, col 22: Error: Expected end of input, got '.'"
    #code: 0
    #file: "[/REDACTED/vendor/tmilos/scim-filter-parser/src/Error/FilterException.php](file:///REDACTED/vendor/tmilos/scim-filter-parser/src/Error/FilterException.php#L24)"
    #line: 24
    -previous: Tmilos\ScimFilterParser\Error\FilterException {#3104 …}
    trace: {▼
      [/REDACTED/vendor/tmilos/scim-filter-parser/src/Error/FilterException.php:24](file:///REDACTED/vendor/tmilos/scim-filter-parser/src/Error/FilterException.php#L24) {▶}
      [/REDACTED/vendor/tmilos/scim-filter-parser/src/Parser.php:407](file:///REDACTED/vendor/tmilos/scim-filter-parser/src/Parser.php#L407) {▶}
      [/REDACTED/vendor/tmilos/scim-filter-parser/src/Parser.php:379](file:///REDACTED/vendor/tmilos/scim-filter-parser/src/Parser.php#L379) {▶}
      [/REDACTED/vendor/tmilos/scim-filter-parser/src/Parser.php:97](file:///REDACTED/vendor/tmilos/scim-filter-parser/src/Parser.php#L97) {▶}

Support for URI in attribute path

SCIM defines URI can be part of the attribute path

attrPath  = [URI ":"] ATTRNAME *1subAttr

For example

urn:ietf:params:scim:schemas:core:2.0:User:userName sw "J"

Current implementation does not support URI

README.md example incorrect?

I'm just testing out this library and finding that the first example under Path mode

$parser = new Parser(Mode::FILTER());
$node = $parser->parse('members[value eq "2819c223-7f76-453a-919d-413861904646"].displayName');

Throws an error

ScimFilterParser\Error\FilterException: [Syntax Error] line 0, col 56: Error: Expected end of input, got '.'

I assume this is just because Parser(Mode::FILTER()); needs to be new Parser(Mode::PATH()); ?

Support for v2 fetch path

SCIM v2 for fetch operations defines parsable path with grammar

PATH = attrPath / valuePath [subAttr]

Parser should be able to read syuch input in obviously different PATH mode then so far supported FILTER mode.

Reject invalid input

Parser can accept invalid input for certain cases.
For example when value path is following with sub attribute

addresses[type eq "work"].streetAddress co "main"

At the end of parsing it must match the end of input to validate whole string matches the syntax.

More than two cases

I played around with the filter parser and I've observed that if you try to use 3 or more cases, it fails. Example:

userName co 'foo' or userName co 'bar' or userName co 'baz'.

To my knowledge, the SCIM specification does not specify a limit of only 2 terms.