Merge pull request #16 from josantonius/release/2.0.0

Release/2.0.0

Author: josantonius

.github/lang/es-ES/README.md

@@ -20,7 +20,6 @@ Biblioteca PHP para la gestión de archivos JSON.
 - [Cómo empezar](#cómo-empezar)
 - [Uso](#uso)
 - [Tests](#tests)
-- [Manejo de excepciones](#manejo-de-excepciones)
 - [Tareas pendientes](#☑-tareas-pendientes)
 - [Registro de cambios](#registro-de-cambios)
 - [Contribuir](#contribuir)
@@ -33,9 +32,14 @@ Biblioteca PHP para la gestión de archivos JSON.
 
 Esta biblioteca es compatible desde la versión **8.0** de PHP hasta la versión **8.1** de PHP.
 
-Para versiones anteriores de PHP (desde la **5.6** hasta la **7.4**) puedes utilizar la
+Para seguir utilizando la versión con métodos estáticos sin las nuevas características:
+
+- Para versiones anteriores de PHP (desde la **5.6** hasta la **7.4**), puedes utilizar la
 [versión 1.1.9](https://github.com/josantonius/php-json/tree/1.1.9) de esta biblioteca.
 
+- Para las versiones **8.0** y **8.1** de PHP, puedes utilizar la
+[version 1.2.0](https://github.com/josantonius/php-json/tree/1.2.0) de esta biblioteca.
+
 ## Instalación
 
 La mejor forma de instalar esta extensión es a través de [Composer](http://getcomposer.org/download/).
@@ -59,68 +63,49 @@ También puedes **clonar el repositorio** completo con Git:
 git clone https://github.com/josantonius/php-json.git
 ```
 
-O **instalarlo manualmente**:
-
-Descargar [Json.php](https://raw.githubusercontent.com/josantonius/php-json/main/src/Json.php),
-[JsonLastError.php](https://raw.githubusercontent.com/josantonius/php-json/main/src/JsonLastError.php) y
-[JsonException.php](https://raw.githubusercontent.com/josantonius/php-json/main/src/Exception/JsonException.php):
-
-```console
-wget https://raw.githubusercontent.com/josantonius/php-json/main/src/Json.php
-```
-
-```console
-wget https://raw.githubusercontent.com/josantonius/php-json/main/src/JsonLastError.php
-```
-
-```console
-wget https://raw.githubusercontent.com/josantonius/php-json/main/src/Exception/JsonException.php
-```
-
 ## Métodos disponibles
 
 Métodos disponibles en esta biblioteca:
 
-### Crear archivo JSON desde array
+### Obtener el contenido del archivo JSON
 
 ```php
-Json::arrayToFile($array, $file);
+$json->get();
 ```
 
-| Atributo | Descripción | Tipo | Requerido | Predeterminado
-| --- | --- | --- | --- | --- |
-| $array | Array a guardar en archivo JSON. | array | Sí | |
-| $file | Ruta hacia el archivo. | string | Sí | |
+**@throws** _CreateDirectoryException_ | _CreateFileException_ | _JsonErrorException_
 
-**# Return** (boolean)
+**@Return** `array` - _Contenido del archivo_
 
-### Guardar en array el contenido de archivo JSON
+### Establecer el contenido del archivo JSON
 
 ```php
-Json::fileToArray($file);
+$json->set(array|object $content);
 ```
 
-| Atributo | Descripción | Tipo | Requerido | Predeterminado
-| --- | --- | --- | --- | --- |
-| $file | Ruta o URL externa al archivo JSON. | string | Sí | |
+**@throws** _CreateFileException_ | _JsonErrorException_ | _UnavailableMethodException_
 
-**# Return** (array|false)
+**@Return** `void`
 
-### Comprobar si hay errores
+### Fusionar en el archivo JSON
 
 ```php
-JsonLastError::check();
+$json->merge(array|object $content);
 ```
 
-**# Return** (array|null) → Null si no hay errores o array con código de estado y mensaje de error.
+**@throws** _CreateFileException_ | _GetFileException_ | _JsonErrorException_ | _UnavailableMethodException_
 
-### Obtener colección de errores JSON
+**@Return** `array` - _Array resultante_
+
+### Incluir en el archivo JSON
 
 ```php
-JsonLastError::getCollection();
+$json->push(array|object $content);
 ```
 
-**# Return** (array) → Recopilación de posibles errores.
+**@throws** _CreateFileException_ | _GetFileException_ | _JsonErrorException_ | _UnavailableMethodException_
+
+**@Return** `array` - _Array resultante_
 
 ## Cómo empezar
 
@@ -132,56 +117,94 @@ require __DIR__ . '/vendor/autoload.php';
 use josantonius\Json\Json;
 ```
 
-Si la instalaste **manualmente**, utiliza:
+```php
+$json = new Json('path/to/file.json');
+
+# Si el archivo no existe, se creará.
+```
+
+O
 
 ```php
-require_once __DIR__ . '/Json.php';
-require_once __DIR__ . '/JsonLastError.php';
-require_once __DIR__ . '/JsonException.php';
+$json = new Json('https://site.com/file.json');
 
-use josantonius\Json\Json;
+# Cuando el archivo JSON se obtiene desde una URL, sólo estará disponible el método "get".
 ```
 
 ## Uso
 
 Ejemplo de uso para esta biblioteca:
 
-### Crear un archivo JSON desde un array
+### Obtener el contenido del archivo
 
-```php
-$array = [
- 'name'  => 'josantonius',
-    'email' => 'info@josantonius.com',
-    'url'   => 'https://github.com/josantonius/php-json'
-];
+```json
+{
+    "foo": "bar"
+}
+```
 
-$pathfile = __DIR__ . '/filename.json';
+```php
+$json->get();
+```
 
-Json::arrayToFile($array, $pathfile);
+```php
+['foo' => 'bar']
 ```
 
-### Guardar en un array el contenido de un archivo JSON
+### Establecer el contenido del archivo
 
 ```php
-$pathfile = __DIR__ . '/filename.json';
+$json->set(['foo' => 'bar']);
+```
 
-$array = Json::fileToArray($pathfile);
+```json
+{
+    "foo": "bar"
+}
 ```
 
-### Comprobar si hubo errores
+### Fusionar en el archivo
+
+```json
+{
+    "foo": "bar"
+}
+```
 
 ```php
-$lastError = JsonLastError::check();
+$json->merge(['bar' => 'foo']);
+```
 
-if (!is_null($lastError)) {
-    var_dump($lastError);
+```json
+{
+    "foo": "bar",
+    "bar": "foo"
 }
 ```
 
-### Obtener colección con errores JSON
+### Incluir en el archivo
+
+```json
+[
+    {
+        "name": "foo"
+    }
+]
+```
 
 ```php
-$jsonLastErrorCollection = JsonLastError::getCollection();
+$json->push(['name'  => 'bar']);
+```
+
+```json
+[
+    {
+        "name": "foo"
+    },
+    {
+        "name": "bar"
+    }
+]
 ```
 
 ## Tests
@@ -227,10 +250,6 @@ Ejecutar todas las pruebas anteriores:
 composer tests
 ```
 
-## Manejo de excepciones
-
-Esta biblioteca utiliza [control de excepciones](src/Exception) que puedes personalizar a tu gusto.
-
 ## ☑ Tareas pendientes
 
 - [ ] Añadir nueva funcionalidad.
@@ -254,8 +273,8 @@ _pull request_, comenzar una discusión o reportar un _issue_.
 
 ## Patrocinar
 
-Si este proyecto te ayuda a reducir el tiempo de desarrollo,
-[¡puedes patrocinarme!](https://github.com/josantonius/lang/es-ES/README.md#patrocinar) :blush:
+Si este proyecto te ayuda a reducir el tiempo de desarrollo y quieres agradecérmelo,
+[¡podrías patrocinarme!](https://github.com/josantonius/lang/es-ES/README.md#patrocinar) :blush:
 
 ## Licencia
 

.github/workflows/ci.yml

@@ -56,7 +56,7 @@ jobs:
         with:
           php-version: '${{ matrix.php }}'
           coverage: 'none'
-          tools: 'composer:v6'
+          tools: 'composer:v2'
 
       - name: 'Install dependencies'
         run: |
@@ -77,7 +77,7 @@ jobs:
         uses: 'shivammathur/setup-php@v2'
         with:
           php-version: '8.1'
-          tools: 'composer:v6'
+          tools: 'composer:v2'
 
       - name: 'Install dependencies'
         run: |

.gitignore

@@ -1,4 +1,5 @@
 vendor/
+coverage/
 .vscode/
 composer.phar
 composer.lock

CHANGELOG.md

@@ -1,5 +1,78 @@
 # CHANGELOG
 
+## [2.0.0](https://github.com/josantonius/php-json/releases/tag/2.0.0) (2022-06-16)
+
+* The library was completely refactored.
+
+* Static methods are no longer used.
+
+* New methods were added to merge and push content in JSON files.
+
+* The JSON error handling class was removed in preference to a single method.
+
+* To continue using the version with static methods without the new features:
+
+  * For older versions of PHP (from **5.6** to **7.4**),
+[version 1.1.9](https://github.com/josantonius/php-json/tree/1.1.9) of this library can be used.
+
+  * For PHP versions **8.0** and **8.1**,
+[version 1.2.0](https://github.com/josantonius/php-json/tree/1.2.0) of this library can be used.
+
+* Deprecated `Josantonius\Json\Json::arrayToFile` method.
+* Deprecated `Josantonius\Json\Json::fileToArray` method.
+
+* Deleted `Josantonius\Json\Exception\JsonException` class.
+* Deleted `Josantonius\Json\JsonLastError` class.
+* Deleted `Josantonius\Json\Tests\JsonLastErrorTest` class.
+
+* Added `Josantonius\Json\Exception\CreateDirectoryException` class.
+* Added `Josantonius\Json\Exception\CreateFileException` class.
+* Added `Josantonius\Json\Exception\GetFileException` class.
+* Added `Josantonius\Json\Exception\JsonErrorException` class.
+* Added `Josantonius\Json\Exception\UnavailableMethodException` class.
+
+* Deleted `Josantonius\Json\Json::createDirectory` method.
+* Deleted `Josantonius\Json\Json::saveFile` method.
+
+* Added `Josantonius\Json\Json->__construct()` method.
+* Added `Josantonius\Json\Json->get()` method.
+* Added `Josantonius\Json\Json->set()` method.
+* Added `Josantonius\Json\Json->merge()` method.
+* Added `Josantonius\Json\Json->push()` method.
+* Added `Josantonius\Json\Json->createFileIfNotExists()` private method.
+* Added `Josantonius\Json\Json->createDirIfNotExists()` private method.
+* Added `Josantonius\Json\Json->getFileContents()` private method.
+* Added `Josantonius\Json\Json->saveToJsonFile()` private method.
+* Added `Josantonius\Json\Json->checkJsonLastError()` private method.
+
+* Deleted `JsonTest->testGetCollection()` method.
+* Deleted `JsonTest->testArrayToFileCreateFileException()` method.
+* Deleted `JsonTest->testFileToArray()` method.
+* Deleted `JsonTest->testFileToArrayCreateFileException()` method.
+* Deleted `JsonTest->testExternalFileToArray()` method.
+* Deleted `JsonTest->testExternalFileNonExistentToArray()` method.
+
+* Added `JsonTest->itShouldReturnValidInstance()` method.
+* Added `JsonTest->constructorShouldCreateTheFileIfNotExist()` method.
+* Added `JsonTest->constructorShouldThrowExceptionIfPathIsWrong()` method.
+* Added `JsonTest->constructorShouldThrowExceptionIfFilenameIsWrong()` method.
+* Added `JsonTest->itShouldGetFileContents()` method.
+* Added `JsonTest->itShouldGetRemoteFileContents()` method.
+* Added `JsonTest->itShouldSetArrayOnJsonFile()` method.
+* Added `JsonTest->itShouldSetObjectOnJsonFile()` method.
+* Added `JsonTest->itShouldThrowExceptionIfSetMethodIsUsedWithRemoteFile()` method.
+* Added `JsonTest->itShouldMergeArrayOnJsonFile()` method.
+* Added `JsonTest->itShouldMergeObjectOnJsonFile()` method.
+* Added `JsonTest->itShouldThrowExceptionIfMergeMethodIsUsedWithRemoteFile()` method.
+* Added `JsonTest->itShouldPushArrayOnJsonFile()` method.
+* Added `JsonTest->itShouldPushObjectOnJsonFile()` method.
+* Added `JsonTest->itShouldThrowExceptionIfPushMethodIsUsedWithRemoteFile()` method.
+* Added `JsonTest->itShouldThrowExceptionIfFileCannotBeObtained()` method.
+* Added `JsonTest->itShouldThrowExceptionIfRemoteFileCannotBeObtained()` method.
+* Added `JsonTest->itShouldThrowExceptionWhenThereAreJsonErrorsInTheFile()` method.
+* Added `JsonTest->arrayToFileStaticMethodShouldBehaveLikeTheSetMethod()` method.
+* Added `JsonTest->fileToArrayStaticMethodShouldBehaveLikeTheGetMethod()` method.
+
 ## [1.2.0](https://github.com/josantonius/php-json/releases/tag/1.2.0) (2022-06-13)
 
 * Support for PHP version **8.0** and higher.
@@ -128,7 +201,8 @@
 
 ## [1.1.2](https://github.com/josantonius/php-json/releases/tag/1.1.2) (2017-05-31)
 
-* The file exception not found in the `fileToArray()` method was deleted. Now if it does not exist the file will create it with an empty array.
+* The file exception not found in the `fileToArray()` method was deleted.
+Now if it does not exist the file will create it with an empty array.
 
 * `JSON_PRETTY_PRINT` was added at time to create the json file.
 
@@ -142,7 +216,8 @@
 
 ## [1.0.0](https://github.com/josantonius/php-json/releases/tag/1.0.0) (2016-12-14)
 
-* Compatible only with PHP 7.0 or higher. In the next versions, the library will be modified to make it compatible with PHP 5.6 or higher.
+* Compatible only with PHP 7.0 or higher.
+In the next versions, the library will be modified to make it compatible with PHP 5.6 or higher.
 
 * Added `Josantonius\Json\Json` class.
 * Added `Josantonius\Json\Json::arrayToFile()` method.