Merge pull request #4 from wayofdev/docs/readme

Author: lotyp

README.md

@@ -17,34 +17,65 @@
 <a href="https://packagist.org/packages/wayofdev/laravel-symfony-serializer"><img src="https://img.shields.io/packagist/l/wayofdev/laravel-symfony-serializer?style=flat-square&color=blue" alt="Software License"/></a>
 <a href="https://packagist.org/packages/wayofdev/laravel-symfony-serializer"><img alt="Commits since latest release" src="https://img.shields.io/github/commits-since/wayofdev/laravel-symfony-serializer/latest?style=flat-square"></a>
 </div>
-
 <br>
 
-# Laravel Package Template
+# Laravel Symfony Serializer
 
-This is minimal Laravel template which is used by other PHP projects in wayofdev organization.
+## 📄 About
 
-If you **like/use** this package, please consider **starring** it. Thanks!
+This package integrates the Symfony Serializer component into Laravel, providing a powerful tool for serializing and deserializing objects into various formats such as JSON, XML, CSV, and YAML.
 
-![Screenshot](assets/screenshot.png)
+Detailed documentation on the Symfony serializer can be found on their [official page](https://symfony.com/doc/current/components/serializer.html).
 
-## 💿 Installation
+### → Purpose
+
+This package brings the power of the Symfony Serializer component to Laravel. While Laravel does not have a built-in serializer and typically relies on array or JSON transformations, this package provides more advanced serialization capabilities. This includes object normalization, handling of circular references, property grouping, and format-specific encoders.
+
+If you are building a REST API, working with queues, or have complex serialization needs, this package will be especially useful. It allows you to use objects as payload instead of simple arrays, and supports various formats such as JSON, XML, CSV, and YAML. This documentation will guide you through the installation process and provide examples of how to use the package to serialize and deserialize your objects.
 
-### → Using composer
+<br>
+
+🙏 If you find this repository useful, please consider giving it a ⭐️. Thank you!
+
+<br>
+
+## 💿 Installation
 
 Require as dependency:
 
 ```bash
 $ composer req wayofdev/laravel-symfony-serializer
 ```
 
+You can publish the config file with:
+
+```bash
+$ php artisan vendor:publish \
+		--provider="WayOfDev\Serializer\Bridge\Laravel\Providers\SerializerServiceProvider" \
+		--tag="config"
+```
+
+<br>
+
+## 💻 Usage
+
+The package provides a list of serializers that can be used to serialize and deserialize objects.
+
+The serializers available in this package are: `symfony-json`, `symfony-csv`, `symfony-xml`, `symfony-yaml`.
+
+> **Warning**
+> The `yaml` encoder requires the `symfony/yaml` package and is disabled when the package is not installed.
+> Install the `symfony/yaml` package and the encoder will be automatically enabled.
+
+@todo ...
+
 <br>
 
 ## 🧪 Running Tests
 
 ### → PHPUnit tests
 
-To run tests, run the following command:
+To run phpunit and pest tests, run the following command:
 
 ```bash
 $ make test
@@ -55,15 +86,15 @@ $ make test
 Code quality using PHPStan:
 
 ```bash
-$ make stan
+$ make lint-stan
 ```
 
 ### → Coding Standards Fixing
 
 Fix code using The PHP Coding Standards Fixer (PHP CS Fixer) to follow our standards:
 
 ```bash
-$ make cs-fix
+$ make lint-php
 ```
 
 <br>
@@ -76,6 +107,27 @@ $ make cs-fix
 
 ## 🙆🏼‍♂️ Author Information
 
-Created in **2022** by [lotyp / wayofdev](https://github.com/wayofdev)
+Created in **2023** by [lotyp / wayofdev](https://github.com/wayofdev)
 
 <br>
+
+## 🙌 Want to Contribute?
+
+Thank you for considering contributing to the wayofdev community! We are open to all kinds of contributions. If you want to:
+
+- 🤔 Suggest a feature
+- 🐛 Report an issue
+- 📖 Improve documentation
+- 👨‍💻 Contribute to the code
+
+<br>
+
+## 🧱 Credits and Useful Resources
+
+This repository is based on code from following repositories:
+
+* [spiral/serializer](https://github.com/spiral/serializer)
+* [spiral-packages/symfony-serializer](https://github.com/spiral-packages/symfony-serializer)
+* [jeromegamez/ramsey-uuid-normalizer](https://github.com/jeromegamez/ramsey-uuid-normalizer)
+* [wayofdev/laravel-jms-serializer](https://github.com/wayofdev/laravel-jms-serializer)
+

config/serializer.php

@@ -7,42 +7,48 @@
 
 return [
     /*
-     * Name (format) of the default serializer that will be registered in SerializerManager.
+     * The 'default' key specifies the name (format) of the default serializer
+     * that will be registered in SerializerManager. This can be overridden
+     * by setting the SERIALIZER_DEFAULT_FORMAT environment variable.
      */
-    'default' => 'json',
+    'default' => env('SERIALIZER_DEFAULT_FORMAT', 'json'),
 
     /*
-     * Supported serializers: json, csv, xml, yaml
-     * Set serializer to false to disable it.
+     * The 'serializers' key lists the supported serializers: json, csv, xml, yaml.
+     * Set a serializer to "false" to disable it. This can be overridden by setting
+     * the corresponding SERIALIZER_USE_* environment variable.
      */
     'serializers' => [
-        'json' => true,
-        'csv' => false,
-        'xml' => false,
-        'yaml' => false,
+        'json' => env('SERIALIZER_USE_JSON', true),
+        'csv' => env('SERIALIZER_USE_CSV', false),
+        'xml' => env('SERIALIZER_USE_XML', false),
+        'yaml' => env('SERIALIZER_USE_YAML', false),
     ],
 
     /*
-     * Register your custom normalizers here.
-     * Default normalizers are registered in src/NormalizersRegistry.php
+     * The 'normalizers' key allows you to register your custom normalizers.
+     * Default normalizers are registered in src/NormalizersRegistry.php.
+     * Uncomment the line below and replace with your custom normalizer if needed
+     * to merge with default ones.
      */
     'normalizers' => [
         // Symfony\Component\Messenger\Transport\Serialization\Normalizer\FlattenExceptionNormalizer
     ],
 
     /*
-     * Register your custom encoders here.
-     * Default encoders are registered in src/EncodersRegistry.php
-     *
-     * Default encoders are:
-     * - Symfony\Component\Serializer\Encoder\JsonEncoder
-     * - Symfony\Component\Serializer\Encoder\CsvEncoder
-     * - Symfony\Component\Serializer\Encoder\XmlEncoder
-     * - Symfony\Component\Serializer\Encoder\YamlEncoder
+     * The 'encoders' key allows you to register your custom encoders.
+     * Default encoders are registered in src/EncodersRegistry.php.
+     * Default encoders include JsonEncoder, CsvEncoder, XmlEncoder, and YamlEncoder.
+     * Uncomment the line below and replace with your custom encoder if needed.
      */
     'encoders' => [
         // Symfony\Component\Serializer\Encoder\JsonEncoder
     ],
 
+    /*
+     * The 'metadata_loader' key specifies the loader for class metadata.
+     * The default loader uses Doctrine annotations. If you want to use a different
+     * metadata format (e.g., YAML, XML), you can replace this with a different loader.
+     */
     'metadata_loader' => new AnnotationLoader(new AnnotationReader()),
 ];