added support for manipulating and writing schema files

fixes #18

Author: cebe

README.md

@@ -1,6 +1,6 @@
 # php-openapi
 
-READ [OpenAPI](https://www.openapis.org/) 3.0.x YAML and JSON files and make the content accessible in PHP objects.
+Read and write [OpenAPI](https://www.openapis.org/) 3.0.x YAML and JSON files and make the content accessible in PHP objects.
 
 It also provides a CLI tool for validating and converting OpenAPI 3.0.x YAML and JSON files.
 
@@ -19,7 +19,7 @@ It also provides a CLI tool for validating and converting OpenAPI 3.0.x YAML and
 
 ## Used by
 
-This library provides a low level API for reading OpenAPI files. It is used by higher level tools to
+This library provides a low level API for reading and writing OpenAPI files. It is used by higher level tools to
 do awesome work:
 
 - https://github.com/cebe/yii2-openapi Code Generator for REST API from OpenAPI spec, includes fake data generator.
@@ -105,6 +105,44 @@ foreach($openapi->paths as $path => $definition) {
 Object properties are exactly like in the [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#openapi-specification).
 You may also access additional properties added by specification extensions.
 
+### Writing Specification files
+
+```php
+// create base description
+$openapi = new \cebe\openapi\spec\OpenApi([
+    'openapi' => '3.0.2',
+    'info' => [
+        'title' => 'Test API',
+        'version' => '1.0.0',
+    ],
+    'paths' => [],
+]);
+// manipulate description as needed
+$openapi->paths['/test'] = new \cebe\openapi\spec\PathItem([
+    'description' => 'something'
+]);
+// ...
+
+$json = \cebe\openapi\Writer::writeToJson($openapi);
+```
+
+results in the following JSON data:
+
+```json
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "Test API",
+        "version": "1.0.0"
+    },
+    "paths": {
+        "/test": {
+            "description": "something"
+        }
+    }
+}
+```
+
 ### Reading Specification Files and Resolving References
 
 In the above we have passed the raw JSON or YAML data to the Reader. In order to be able to resolve

src/SpecBaseObject.php

@@ -265,7 +265,7 @@ public function __get($name)
 
     public function __set($name, $value)
     {
-        throw new ReadonlyPropertyException('Setting read-only property: ' . \get_class($this) . '::' . $name);
+        $this->_properties[$name] = $value;
     }
 
     public function __isset($name)
@@ -279,7 +279,7 @@ public function __isset($name)
 
     public function __unset($name)
     {
-        throw new ReadonlyPropertyException('Unsetting read-only property: ' . \get_class($this) . '::' . $name);
+        unset($this->_properties[$name]);
     }
 
     /**

src/spec/Callback.php

@@ -58,14 +58,30 @@ public function getUrl()
         return $this->_url;
     }
 
+    /**
+     * @param string $url
+     */
+    public function setUrl(string $url): void
+    {
+        $this->_url = $url;
+    }
+
     /**
      * @return PathItem
      */
-    public function getRequest()
+    public function getRequest(): ?PathItem
     {
         return $this->_pathItem;
     }
 
+    /**
+     * @param PathItem $request
+     */
+    public function setRequest(?PathItem $request): void
+    {
+        $this->_pathItem = $request;
+    }
+
     /**
      * Validate object data according to OpenAPI spec.
      * @return bool whether the loaded data is valid according to OpenAPI spec

src/spec/Encoding.php

@@ -30,8 +30,6 @@ class Encoding extends SpecBaseObject
     protected function attributes(): array
     {
         return [
-            // TODO implement default values for contentType
-            // https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#encodingObject
             'contentType' => Type::STRING,
             'headers' => [Type::STRING, Header::class],
             // TODO implement default values for style
@@ -42,16 +40,49 @@ protected function attributes(): array
         ];
     }
 
+    private $_attributeDefaults = [];
+
+    /**
+     * @return array array of attributes default values.
+     */
+    protected function attributeDefaults(): array
+    {
+        return $this->_attributeDefaults;
+    }
+
     /**
      * Create an object from spec data.
      * @param array $data spec data read from YAML or JSON
      * @throws TypeErrorException in case invalid data is supplied.
      */
-    public function __construct(array $data)
+    public function __construct(array $data, ?Schema $schema = null)
     {
-        if (!isset($data['explode']) && isset($data['style'])) {
+        if (isset($data['style'])) {
             // Spec: When style is form, the default value is true.
-            $data['explode'] = ($data['style'] === 'form');
+            $this->_attributeDefaults['explode'] = ($data['style'] === 'form');
+        }
+        if ($schema !== null) {
+            // Spec: Default value depends on the property type:
+            // for string with format being binary – application/octet-stream;
+            // for other primitive types – text/plain;
+            // for object - application/json;
+            // for array – the default is defined based on the inner type.
+            switch ($schema->type === 'array' ? ($schema->items->type ?? 'array') : $schema->type) {
+                case Type::STRING:
+                    if ($schema->format === 'binary') {
+                        $this->_attributeDefaults['contentType'] = 'application/octet-stream';
+                        break;
+                    }
+                    // no break here
+                case Type::BOOLEAN:
+                case Type::INTEGER:
+                case Type::NUMBER:
+                    $this->_attributeDefaults['contentType'] = 'text/plain';
+                    break;
+                case 'object':
+                    $this->_attributeDefaults['contentType'] = 'application/json';
+                    break;
+            }
         }
         parent::__construct($data);
     }

src/spec/MediaType.php

@@ -7,6 +7,7 @@
 
 namespace cebe\openapi\spec;
 
+use cebe\openapi\exceptions\TypeErrorException;
 use cebe\openapi\SpecBaseObject;
 
 /**
@@ -34,6 +35,27 @@ protected function attributes(): array
         ];
     }
 
+    /**
+     * Create an object from spec data.
+     * @param array $data spec data read from YAML or JSON
+     * @throws TypeErrorException in case invalid data is supplied.
+     */
+    public function __construct(array $data)
+    {
+        // instantiate Encoding by passing the schema for extracting default values
+        $encoding = $data['encoding'] ?? null;
+        unset($data['encoding']);
+
+        parent::__construct($data);
+
+        if (!empty($encoding)) {
+            foreach($encoding as $property => $encodingData) {
+                $encoding[$property] = new Encoding($encodingData, $this->schema->properties[$property] ?? null);
+            }
+            $this->encoding = $encoding;
+        }
+    }
+
     /**
      * Perform validation on this object, check data against OpenAPI Specification rules.
      */

src/spec/Paths.php

@@ -84,6 +84,23 @@ public function getPath(string $name): ?PathItem
         return $this->_paths[$name] ?? null;
     }
 
+    /**
+     * @param string $name path name
+     * @param PathItem $pathItem the path item to add
+     */
+    public function addPath(string $name, PathItem $pathItem): void
+    {
+        $this->_paths[$name] = $pathItem;
+    }
+
+    /**
+     * @param string $name path name
+     */
+    public function removePath(string $name): void
+    {
+        unset($this->_paths[$name]);
+    }
+
     /**
      * @return PathItem[]
      */
@@ -163,7 +180,7 @@ public function offsetGet($offset)
      */
     public function offsetSet($offset, $value)
     {
-        throw new ReadonlyPropertyException('Setting read-only property: ' . \get_class($this) . '::' . $offset);
+        $this->addPath($offset, $value);
     }
 
     /**
@@ -174,7 +191,7 @@ public function offsetSet($offset, $value)
      */
     public function offsetUnset($offset)
     {
-        throw new ReadonlyPropertyException('Unsetting read-only property: ' . \get_class($this) . '::' . $offset);
+        $this->removePath($offset);
     }
 
     /**

src/spec/Responses.php

@@ -84,6 +84,23 @@ public function getResponse($statusCode)
         return $this->_responses[$statusCode] ?? null;
     }
 
+    /**
+     * @param string $statusCode HTTP status code
+     * @param Response|Reference $response
+     */
+    public function addResponse($statusCode, $response): void
+    {
+        $this->_responses[$statusCode] = $response;
+    }
+
+    /**
+     * @param string $statusCode HTTP status code
+     */
+    public function removeResponse($statusCode)
+    {
+        unset($this->_responses[$statusCode]);
+    }
+
     /**
      * @return Response[]|Reference[]
      */
@@ -159,7 +176,7 @@ public function offsetGet($offset)
      */
     public function offsetSet($offset, $value)
     {
-        throw new ReadonlyPropertyException('Setting read-only property: ' . \get_class($this) . '::' . $offset);
+        $this->addResponse($offset, $value);
     }
 
     /**
@@ -170,7 +187,7 @@ public function offsetSet($offset, $value)
      */
     public function offsetUnset($offset)
     {
-        throw new ReadonlyPropertyException('Unsetting read-only property: ' . \get_class($this) . '::' . $offset);
+        $this->removeResponse($offset);
     }
 
     /**

tests/WriterTest.php

@@ -35,6 +35,35 @@ public function testWriteJson()
         );
     }
 
+    public function testWriteJsonMofify()
+    {
+        $openapi = $this->createOpenAPI();
+
+        $openapi->paths['/test'] = new \cebe\openapi\spec\PathItem([
+            'description' => 'something'
+        ]);
+
+        $json = \cebe\openapi\Writer::writeToJson($openapi);
+
+        $this->assertEquals(preg_replace('~\R~', "\n", <<<JSON
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "Test API",
+        "version": "1.0.0"
+    },
+    "paths": {
+        "\/test": {
+            "description": "something"
+        }
+    }
+}
+JSON
+),
+            $json
+        );
+    }
+
     public function testWriteYaml()
     {
         $openapi = $this->createOpenAPI();