From db18b1e625777465bd76450559ffa2fa7994ad17 Mon Sep 17 00:00:00 2001
From: Antoine Lelaisant <antoine.lelaisant@knplabs.com>
Date: Tue, 27 Sep 2022 14:54:03 +0200
Subject: [PATCH] doc: added documentation in the readme

---
 README.md                   | 212 ++++++++++++++++++++++++++++++++++++
 composer.json               |   2 +-
 src/JsonSchema.php          |   8 +-
 src/JsonSchemaInterface.php |  11 ++
 4 files changed, 227 insertions(+), 6 deletions(-)
 create mode 100644 README.md
 create mode 100644 src/JsonSchemaInterface.php

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f903702
--- /dev/null
+++ b/README.md
@@ -0,0 +1,212 @@
+# php-json-schema
+
+A PHP implementation of [JSON Schema](http://json-schema.org/). This library allows you to create JSON Schema objects and validate JSON data against them.
+
+# Installation
+
+Install the latest version with
+
+```bash
+$ composer require knplabs/php-json-schema
+```
+
+# Basic Usage
+
+A JsonSchema must implements `KnpLabs\JsonSchema\JsonSchemaInterface` (which is basically an alias for `JsonSerializable`).
+
+## Default JsonSchema
+
+There is already a default implementation of `JsonSchemaInterface` called `KnpLabs\JsonSchema\JsonSchema` which is an abstract class. This class provides some static methods to create some common JSON Schema scalars or objects.
+
+## Scalars
+
+### `JsonSchema::string()`
+
+```php
+use KnpLabs\JsonSchema\JsonSchema;
+
+$schema = JsonSchema::create(
+    'firstName',                       // The name of the property
+    'Hold the first name of the user', // The description of the property
+    ['John', 'Georges'],               // Some examples of possible values
+    JsonSchema::string()               // The type of the property
+);
+```
+
+### `JsonSchema::text()`
+
+```php
+use KnpLabs\JsonSchema\JsonSchema;
+
+$schema = JsonSchema::create(
+    'content',                    // The name of the property
+    'The content of the article', // The description of the property
+    ['Lorem ipsum...'],           // Some examples of possible values
+    JsonSchema::text()            // The type of the property
+);
+```
+
+### `JsonSchema::integer()`
+
+```php
+use KnpLabs\JsonSchema\JsonSchema;
+
+$schema = JsonSchema::create(
+    'age',                            // The name of the property
+    'Hold the age of the user',       // The description of the property
+    [25, 30],                         // Some examples of possible values
+    JsonSchema::integer()             // The type of the property
+);
+```
+
+### `JsonSchema::positiveInteger()`
+
+```php
+use KnpLabs\JsonSchema\JsonSchema;
+
+$schema = JsonSchema::create(
+    'age',                            // The name of the property
+    'Hold the age of the user',       // The description of the property
+    [25, 30],                         // Some examples of possible values
+    JsonSchema::positiveInteger()     // The type of the property
+);
+```
+
+### `JsonSchema::number()`
+
+```php
+use KnpLabs\JsonSchema\JsonSchema;
+
+$schema = JsonSchema::create(
+    'price',                // The name of the property
+    'The price in dollars', // The description of the property
+    [10.8, 30.0],           // Some examples of possible values
+    JsonSchema::number()    // The type of the property
+);
+```
+
+### `JsonSchema::boolean()`
+
+```php
+use KnpLabs\JsonSchema\JsonSchema;
+
+$schema = JsonSchema::create(
+    'isAdult',                      // The name of the property
+    'Hold if the user is an adult', // The description of the property
+    [true, false],                  // Some examples of possible values
+    JsonSchema::boolean()           // The type of the property
+);
+```
+
+### `JsonSchema::date()`
+
+```php
+use KnpLabs\JsonSchema\JsonSchema;
+
+$schema = JsonSchema::create(
+    'createdAt',                    // The name of the property
+    'The date of creation',         // The description of the property
+    ['2015-01-01', '2015-01-02'],   // Some examples of possible values
+    JsonSchema::date()              // The type of the property
+);
+```
+
+## Enum
+
+Enum is a special type of scalar which is a list of possible values.
+They can be created by extending the `KnpLabs\JsonSchema\EnumSchema`:
+
+```php
+<?php
+
+namespace Acme;
+
+use KnpLabs\JsonSchema\EnumSchema;
+
+class RoleEnum extends EnumSchema
+{
+    const ROLE_ADMIN = 'ROLE_ADMIN';
+    const ROLE_USER = 'ROLE_USER';
+
+    public function getTitle(): string
+    {
+        return 'Role enum';
+    }
+
+    public function getDescription(): string
+    {
+        return 'Enum of the possible roles';
+    }
+
+    public static function getEnum()
+    {
+        yield self::ROLE_ADMIN;
+        yield self::ROLE_USER;
+    }
+}
+```
+
+## Objects
+
+You can create objects schema by extending the `KnpLabs\JsonSchema\ObjectSchema` class:
+
+```php
+<?php
+
+namespace Acme;
+
+use KnpLabs\JsonSchema\ObjectSchema;
+
+class PersonSchema extends ObjectSchema
+{
+    public function __construct()
+    {
+        $this->addProperty(
+            'firstName',
+            JsonSchema::create(
+                'firstName',
+                'Hold the first name of the user',
+                ['John', 'Georges'],
+                JsonSchema::string()
+            )
+        );
+
+        $this->addProperty(
+            'lastName',
+            JsonSchema::create(
+                'lastName',
+                'Hold the last name of the user',
+                ['Doe', 'Smith'],
+                JsonSchema::string()
+            )
+        );
+
+        $this->addProperty('role', new RoleEnum());
+    }
+}
+```
+
+## Collections
+
+You can create collections schema by extending the `KnpLabs\JsonSchema\CollectionSchema` class:
+
+```php
+<?php
+
+namespace Acme;
+
+use KnpLabs\JsonSchema\CollectionSchema;
+
+class PersonCollectionSchema extends CollectionSchema
+{
+    public function __construct()
+    {
+        parent::__construct(new PersonSchema());
+    }
+
+    public function getDescription(): string
+    {
+        return 'The list of all the persons';
+    }
+}
+```
\ No newline at end of file
diff --git a/composer.json b/composer.json
index dc1f982..a9c4c98 100644
--- a/composer.json
+++ b/composer.json
@@ -1,5 +1,5 @@
 {
-    "name": "knplabs/json-schema",
+    "name": "knplabs/php-json-schema",
     "description": "PHP json-schema implementation",
     "type": "library",
     "license": "MIT",
diff --git a/src/JsonSchema.php b/src/JsonSchema.php
index 87a628b..ddb3754 100644
--- a/src/JsonSchema.php
+++ b/src/JsonSchema.php
@@ -4,12 +4,10 @@
 
 namespace KnpLabs\JsonSchema;
 
-use JsonSerializable;
-
 /**
  * @template T of mixed
  */
-abstract class JsonSchema implements JsonSerializable
+abstract class JsonSchema implements JsonSchemaInterface
 {
     /**
      * @param JsonSchema<E> $schema
@@ -44,7 +42,7 @@ public static function create(
             /**
              * @var iterable<int, E>
              */
-            private readonly iterable $examples;
+            private iterable $examples;
 
             /**
              * @param iterable<int, E>     $examples
@@ -77,7 +75,7 @@ public function getExamples(): iterable
                 yield from $this->examples;
             }
 
-            protected function getSchema(): array
+            public function getSchema(): array
             {
                 return $this->schema;
             }
diff --git a/src/JsonSchemaInterface.php b/src/JsonSchemaInterface.php
new file mode 100644
index 0000000..75efd9e
--- /dev/null
+++ b/src/JsonSchemaInterface.php
@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KnpLabs\JsonSchema;
+
+use JsonSerializable;
+
+interface JsonSchemaInterface extends JsonSerializable
+{
+}