From 8302acd1d2efd4fc54cb1b2faeef91be64983787 Mon Sep 17 00:00:00 2001 From: Erayd Date: Tue, 27 Jun 2017 19:17:57 +1200 Subject: [PATCH 1/7] Method comments for Validator class --- src/JsonSchema/Validator.php | 39 ++++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/src/JsonSchema/Validator.php b/src/JsonSchema/Validator.php index 5d031881..9cf4a388 100644 --- a/src/JsonSchema/Validator.php +++ b/src/JsonSchema/Validator.php @@ -32,13 +32,21 @@ class Validator extends BaseConstraint const ERROR_SCHEMA_VALIDATION = 0x00000002; /** - * Validates the given data against the schema and returns an object containing the results - * Both the php object and the schema are supposed to be a result of a json_decode call. - * The validation works as defined by the schema proposal in http://json-schema.org. + * Validates the given data against the schema and returns an object containing the results. + * + * Both the value object and the schema are supposed to be the result of a json_decode call, + * or an equivalent value. The validation logic used is a non-compliant superset of the spec + * available at http://json-schema.org/ (versions prior to draft-06). * * Note that the first argument is passwd by reference, so you must pass in a variable. * - * {@inheritdoc} + * @api + * + * @param mixed $value Reference to the value that should be validated against the schema + * @param mixed $schema The schema to validate against + * @param int $checkMode Bitwise list of option flags to enable during validation + * + * @return int Bitwise list of error categories encountered during validation */ public function validate(&$value, $schema = null, $checkMode = null) { @@ -73,7 +81,16 @@ public function validate(&$value, $schema = null, $checkMode = null) } /** - * Alias to validate(), to maintain backwards-compatibility with the previous API + * Alias to validate(), to maintain backwards-compatibility with the previous API. + * + * Equivalent to calling validate() without setting any extra $checkMode options + * + * @api + * + * @param mixed $value The value that should be validated against the schema - *not* a reference + * @param mixed $schema The schema to validate against + * + * @return int Bitwise list of error categories encountered during validation */ public function check($value, $schema) { @@ -81,7 +98,17 @@ public function check($value, $schema) } /** - * Alias to validate(), to maintain backwards-compatibility with the previous API + * Alias to validate(), to maintain backwards-compatibility with the previous API. + * + * Equivalent to calling validate() with CHECK_MODE_COERCE_TYPES as the only additional + * $checkMode option. + * + * @api + * + * @param mixed $value Reference to the value that should be validated against the schema + * @param mixed $schema The schema to validate against + * + * @return int Bitwise list of error categories encountered during validation */ public function coerce(&$value, $schema) { From 95f7c2d7f1a6e35178472cbc770ad7f67a962499 Mon Sep 17 00:00:00 2001 From: Erayd Date: Tue, 27 Jun 2017 19:23:53 +1200 Subject: [PATCH 2/7] Class comment on Validator --- src/JsonSchema/Validator.php | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/JsonSchema/Validator.php b/src/JsonSchema/Validator.php index 9cf4a388..d29f957e 100644 --- a/src/JsonSchema/Validator.php +++ b/src/JsonSchema/Validator.php @@ -15,12 +15,13 @@ use JsonSchema\SchemaStorage; /** - * A JsonSchema Constraint + * The main public interface to the JsonSchema validation library. * - * @author Robert Schönthal - * @author Bruno Prieto Reis + * Validates a document instance against a schema * - * @see README.md + * @package justinrainbow/json-schema + * + * @license MIT */ class Validator extends BaseConstraint { From c4f5d0cb3808da5950213eb1ff2cdcd663117132 Mon Sep 17 00:00:00 2001 From: Erayd Date: Tue, 27 Jun 2017 19:29:07 +1200 Subject: [PATCH 3/7] Minor comment tweaks --- src/JsonSchema/Validator.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/JsonSchema/Validator.php b/src/JsonSchema/Validator.php index d29f957e..092e45b8 100644 --- a/src/JsonSchema/Validator.php +++ b/src/JsonSchema/Validator.php @@ -39,7 +39,7 @@ class Validator extends BaseConstraint * or an equivalent value. The validation logic used is a non-compliant superset of the spec * available at http://json-schema.org/ (versions prior to draft-06). * - * Note that the first argument is passwd by reference, so you must pass in a variable. + * Note that the first argument is passed by reference, so you must pass in a variable. * * @api * @@ -47,7 +47,7 @@ class Validator extends BaseConstraint * @param mixed $schema The schema to validate against * @param int $checkMode Bitwise list of option flags to enable during validation * - * @return int Bitwise list of error categories encountered during validation + * @return int Bitwise list of error categories encountered during validation, or zero for success */ public function validate(&$value, $schema = null, $checkMode = null) { @@ -91,7 +91,7 @@ public function validate(&$value, $schema = null, $checkMode = null) * @param mixed $value The value that should be validated against the schema - *not* a reference * @param mixed $schema The schema to validate against * - * @return int Bitwise list of error categories encountered during validation + * @return int Bitwise list of error categories encountered during validation, or zero for success */ public function check($value, $schema) { @@ -109,7 +109,7 @@ public function check($value, $schema) * @param mixed $value Reference to the value that should be validated against the schema * @param mixed $schema The schema to validate against * - * @return int Bitwise list of error categories encountered during validation + * @return int Bitwise list of error categories encountered during validation, or zero for success */ public function coerce(&$value, $schema) { From 3d89f2c0bcdbb6b0829fac148c8c31d795f51eee Mon Sep 17 00:00:00 2001 From: Erayd Date: Tue, 27 Jun 2017 19:46:12 +1200 Subject: [PATCH 4/7] PHPDoc comments for JsonSchema\Constraints\BaseConstraint --- src/JsonSchema/Constraints/BaseConstraint.php | 80 ++++++++++++++++--- 1 file changed, 68 insertions(+), 12 deletions(-) diff --git a/src/JsonSchema/Constraints/BaseConstraint.php b/src/JsonSchema/Constraints/BaseConstraint.php index 13168d71..e03e2405 100644 --- a/src/JsonSchema/Constraints/BaseConstraint.php +++ b/src/JsonSchema/Constraints/BaseConstraint.php @@ -17,34 +17,51 @@ use JsonSchema\Validator; /** - * A more basic constraint definition - used for the public - * interface to avoid exposing library internals. + * The base constraint definition from which all other constraint classes descend + * + * This class is also used as the base class for Validator, in order to expose some + * common functionality to end users of the library. + * + * @package justinrainbow/json-schema + * + * @license MIT */ class BaseConstraint { /** - * @var array Errors + * @var array List of errors encountered during validation against the current constraint */ protected $errors = array(); /** - * @var int All error types which have occurred + * @var int Bitwise list of all error categories in which a validation error has occurred */ protected $errorMask = Validator::ERROR_NONE; /** - * @var Factory + * @var Factory Factory object containing global state, config options & misc functionality */ protected $factory; /** - * @param Factory $factory + * Create a new constraint instance + * + * @api via JsonSchema\Validator + * + * @param Factory $factory Factory object containing global state, config options & misc functionality */ public function __construct(Factory $factory = null) { $this->factory = $factory ?: new Factory(); } + /** + * Add an error to the list of errors encountered during validation + * + * @param ConstraintError $constraint Which error condition has been encountered + * @param JsonPointer $path Where the error occurred + * @param array $more List of additional parameters used to generate error messages + */ public function addError(ConstraintError $constraint, JsonPointer $path = null, array $more = array()) { $message = $constraint ? $constraint->getMessage() : ''; @@ -74,6 +91,11 @@ public function addError(ConstraintError $constraint, JsonPointer $path = null, $this->errorMask |= $error['context']; } + /** + * Add multiple, already-rendered errors to the current list for this constraint + * + * @param array $errors List of errors to add + */ public function addErrors(array $errors) { if ($errors) { @@ -87,6 +109,18 @@ public function addErrors(array $errors) } } + /** + * Get a list of all errors encountered during validation. + * + * If you only want to return errors in particular categories, set $errorContext to + * include the desired categories. + * + * @api via JsonSchema\Validator + * + * @param int $errorContext Which categories of error to include + * + * @return array List of errors + */ public function getErrors($errorContext = Validator::ERROR_ALL) { if ($errorContext === Validator::ERROR_ALL) { @@ -100,6 +134,18 @@ public function getErrors($errorContext = Validator::ERROR_ALL) }); } + /** + * Return the number of errors encountered during validation. + * + * If you only want to count the errors in particular categories, set $errorContext to + * include the desired categories. + * + * @api via JsonSchema\Validator + * + * @param int $errorContext Which categories of error to include + * + * @return int Number of errors + */ public function numErrors($errorContext = Validator::ERROR_ALL) { if ($errorContext === Validator::ERROR_ALL) { @@ -109,14 +155,22 @@ public function numErrors($errorContext = Validator::ERROR_ALL) return count($this->getErrors($errorContext)); } + /** + * Check whether the most recent validation attempt completed successfully + * + * @api via JsonSchema\Validator + * + * @return bool True if no errors were encountered, false otherwise + */ public function isValid() { return !$this->getErrors(); } /** - * Clears any reported errors. Should be used between - * multiple validation checks. + * Clear the list of reported errors. Should be used between multiple validation attempts. + * + * reset() is called automatically when using JsonSchema\Validator::validate(). */ public function reset() { @@ -125,9 +179,11 @@ public function reset() } /** - * Get the error mask + * Get a list of categories in which a validation error has occurred + * + * @api via JsonSchema\Validator * - * @return int + * @return int Bitwise list of error categories that were encountered */ public function getErrorMask() { @@ -137,9 +193,9 @@ public function getErrorMask() /** * Recursively cast an associative array to an object * - * @param array $array + * @param array $array The array to cast * - * @return object + * @return object The cast object */ public static function arrayToObjectRecursive($array) { From a139c54e6467691c1bbe3f6f9faf53566d6b79d9 Mon Sep 17 00:00:00 2001 From: Erayd Date: Tue, 27 Jun 2017 19:50:33 +1200 Subject: [PATCH 5/7] Comments for JsonSchema\Enum --- src/JsonSchema/Enum.php | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/JsonSchema/Enum.php b/src/JsonSchema/Enum.php index c52f8daa..1d40862c 100644 --- a/src/JsonSchema/Enum.php +++ b/src/JsonSchema/Enum.php @@ -2,6 +2,17 @@ namespace JsonSchema; +/** + * Alias class for \MabeEnum\Enum, so that the underlying class can be easily changed or extended. + * + * This library currently contains no custom functionality, but defines this class so that + * the Enum interface can be preserved if the upstream API changes, or a different Enum package + * is used. + * + * @package justinrainbow\json-schema + * + * @license MIT + */ abstract class Enum extends \MabeEnum\Enum { } From d74c343f354cb04dda421bf2b647c357a4597373 Mon Sep 17 00:00:00 2001 From: Erayd Date: Tue, 27 Jun 2017 19:53:39 +1200 Subject: [PATCH 6/7] Comments for JsonSchema\Rfc3339 --- src/JsonSchema/Rfc3339.php | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/JsonSchema/Rfc3339.php b/src/JsonSchema/Rfc3339.php index adca581a..6ac8239c 100644 --- a/src/JsonSchema/Rfc3339.php +++ b/src/JsonSchema/Rfc3339.php @@ -2,16 +2,24 @@ namespace JsonSchema; +/** + * Helper for creating DateTime objects from an RFC-3339 string + * + * @package justinrainbow\json-schema + * + * @license MIT + */ class Rfc3339 { + /** The regular expression used to tokenize the RFC-3339 date-time string */ const REGEX = '/^(\d{4}-\d{2}-\d{2}[T ]{1}\d{2}:\d{2}:\d{2})(\.\d+)?(Z|([+-]\d{2}):?(\d{2}))$/'; /** - * Try creating a DateTime instance + * Create a DateTime object based on an RFC-3339 string * - * @param string $string + * @param string $string The string to parse * - * @return \DateTime|null + * @return \DateTime|null A DateTime object corresponding to the given string, or null on error */ public static function createFromString($string) { From bbbcd66030e1da4f27590c9bace0305d8c3e8853 Mon Sep 17 00:00:00 2001 From: Erayd Date: Tue, 27 Jun 2017 20:15:51 +1200 Subject: [PATCH 7/7] Comments for JsonSchema\SchemaStorage --- src/JsonSchema/SchemaStorage.php | 60 +++++++++++++++++++++++++++++--- 1 file changed, 56 insertions(+), 4 deletions(-) diff --git a/src/JsonSchema/SchemaStorage.php b/src/JsonSchema/SchemaStorage.php index 58650cd9..6a158e31 100644 --- a/src/JsonSchema/SchemaStorage.php +++ b/src/JsonSchema/SchemaStorage.php @@ -8,14 +8,35 @@ use JsonSchema\Uri\UriResolver; use JsonSchema\Uri\UriRetriever; +/** + * Storage schema for user-provided and retrieved schema objects + * + * @package justinrainbow\json-schema + * + * @license MIT + */ class SchemaStorage implements SchemaStorageInterface { + /** URI used for schemas which are provided by the user and have no associated URI */ const INTERNAL_PROVIDED_SCHEMA_URI = 'internal://provided-schema'; + /** @var UriRetriever UriRetriever instance to use for this SchemaStorage */ protected $uriRetriever; + + /** @var UriResolver UriResolver instance to use for this SchemaStorage */ protected $uriResolver; + + /** @var array List of cached schemas */ protected $schemas = array(); + /** + * Create a new SchemaStorage instance + * + * @api + * + * @param UriRetriever $uriRetriever UriRetriever instance to use for this SchemaStorage (optional) + * @param UriResolver $uriResolver UriResolver instance to use for this SchemaStorage (optional) + */ public function __construct( UriRetrieverInterface $uriRetriever = null, UriResolverInterface $uriResolver = null @@ -25,6 +46,8 @@ public function __construct( } /** + * Get the UriRetriever instance used for this SchemaStorage + * * @return UriRetrieverInterface */ public function getUriRetriever() @@ -33,6 +56,8 @@ public function getUriRetriever() } /** + * Get the UriResolver instance used for this SchemaStorage + * * @return UriResolverInterface */ public function getUriResolver() @@ -41,7 +66,15 @@ public function getUriResolver() } /** - * {@inheritdoc} + * Add a schema to the cache + * + * This method can be used to add a user-provided schema object, or if just a URI is provided, + * can fetch the schema remotely using the configured UriResolver / UriRetriever objects. + * + * @api + * + * @param string $id The unique identifying URI associated with the schema + * @param mixed $schema The schema definition (optional) */ public function addSchema($id, $schema = null) { @@ -107,7 +140,16 @@ private function expandRefs(&$schema, $base = null) } /** - * {@inheritdoc} + * Get a decoded schema + * + * If the schema is present in the cache, it will be returned directly. Otherwise, the library + * will fetch it remotely using the configured UriResolver / UriRetriever objects. + * + * @api + * + * @param string $id The unique identifying URI associated with the schema + * + * @return mixed The decoded schema definition */ public function getSchema($id) { @@ -119,7 +161,12 @@ public function getSchema($id) } /** - * {@inheritdoc} + * Resolve a uri-reference pointer and return the target schema object + * + * @param string $ref The reference to resolve + * @param array $resolveStack Internal list of resolved objects (used for loop detection) + * + * @return mixed The referenced schema object */ public function resolveRef($ref, $resolveStack = array()) { @@ -154,7 +201,12 @@ public function resolveRef($ref, $resolveStack = array()) } /** - * {@inheritdoc} + * Check a schema object for $ref, and resolve it if present. Returns the processed schema object. + * + * @param mixed $refSchema The schema to check + * @param array $resolveStack Internal list of resolved objects (used for loop detection) + * + * @return mixed The final schema object after all $ref properties have been recursively resolved */ public function resolveRefSchema($refSchema, $resolveStack = array()) {