docs: improve and modernize documentation and consistently switch to US English (#273)

Author: martin-georgiev

.coderabbit.yaml

@@ -12,7 +12,7 @@ reviews:
   high_level_summary: true
   path_instructions:
     - path: "tests/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/**/*.php"
-      instructions: "Use the online PostgreSQL's official documentation to check that the tests have comprehensive use-cases and example SQL queries for the tested SQL functions and operators."
+      instructions: "Use the PostgreSQL official documentation to verify that tests include comprehensive use cases and example SQL queries for the tested SQL functions and operators."
   poem: true
   profile: "chill"
   request_changes_workflow: true

.github/FUNDING.yml

@@ -1 +1,2 @@
 github: [martin-georgiev]
+custom: ["https://github.com/sponsors/martin-georgiev"]

README.md

@@ -2,44 +2,110 @@
 [![Coverage Status](https://coveralls.io/repos/github/martin-georgiev/postgresql-for-doctrine/badge.svg?branch=main)](https://coveralls.io/github/martin-georgiev/postgresql-for-doctrine?branch=main)
 [![Latest Stable Version](https://poser.pugx.org/martin-georgiev/postgresql-for-doctrine/version)](https://packagist.org/packages/martin-georgiev/postgresql-for-doctrine)
 [![Total Downloads](https://poser.pugx.org/martin-georgiev/postgresql-for-doctrine/downloads)](https://packagist.org/packages/martin-georgiev/postgresql-for-doctrine)
-----
-## What's this?
-This package provides Doctrine support for some specific PostgreSQL 9.4+ features:
 
-* Support of JSONB and some array data-types (at present integers, BOOL, TEXT and JSONB)
-* Implementation of the most commonly used functions and operators when working with array and JSON data-types
-* Functions for text search
-* Aggregate functions
-* Date functions
+# PostgreSQL for Doctrine
 
-It can be integrated in a simple manner with Symfony, Laravel and other frameworks that make use of Doctrine.
+Enhances Doctrine with PostgreSQL-specific features and functions. Supports PostgreSQL 9.4+ and PHP 8.1+.
 
-You can easily extend package's behaviour with your own array-like data-types or other desired functions. Read more about this in the [contributing guide](docs/CONTRIBUTING.md).
+## Quick Start
 
-----
-## What is available?
-Full set of the available types can be found [here](docs/AVAILABLE-TYPES.md).
+```php
+// Register types with Doctrine
+Type::addType('jsonb', "MartinGeorgiev\\Doctrine\\DBAL\\Types\\Jsonb");
+Type::addType('text[]', "MartinGeorgiev\\Doctrine\\DBAL\\Types\\TextArray");
 
-Full set of the available functions and extra operators can be found [here](docs/AVAILABLE-FUNCTIONS-AND-OPERATORS.md).
+// Use in your Doctrine entities
+#[ORM\Column(type: 'jsonb')]
+private array $data;
 
-----
-## How to install?
-Easiest and recommended way is with [Composer](https://getcomposer.org/download/)
+#[ORM\Column(type: 'text[]')]
+private array $tags;
 
-    composer require martin-georgiev/postgresql-for-doctrine
+// Use in DQL
+$query = $em->createQuery('
+    SELECT e 
+    FROM App\Entity\Post e 
+    WHERE CONTAINS(e.tags, ARRAY[:tags]) = TRUE
+    AND JSON_GET_FIELD(e.data, :field) = :value
+');
+```
 
-----
-## How to integrate with your framework?
-Read the guide with examples for [Symfony](docs/INTEGRATING-WITH-SYMFONY.md).
+## 🚀 Features Highlight
 
-Read the guide with examples for [Laravel](docs/INTEGRATING-WITH-LARAVEL.md).
+This package provides comprehensive Doctrine support for PostgreSQL features:
 
-Read the guide with examples for [Doctrine](docs/INTEGRATING-WITH-DOCTRINE.md).
+### Data Types
+- **Array Types**
+  - Integer arrays (`int[]`, `smallint[]`, `bigint[]`)
+  - Text arrays (`text[]`)
+  - Boolean arrays (`bool[]`)
+  - JSONB arrays (`jsonb[]`)
+- **JSON Types**
+  - Native JSONB support
+  - JSON field operations
+  - JSON construction and manipulation
 
-----
+### PostgreSQL Operators
+- **Array Operations**
+  - Contains (`@>`)
+  - Is contained by (`<@`)
+  - Overlaps (`&&`)
+  - Array aggregation with ordering
+- **JSON Operations**
+  - Field access (`->`, `->>`)
+  - Path operations (`#>`, `#>>`)
+  - JSON containment and existence operators
 
-Check for [common use-cases, examples and known errors](docs/USE-CASES-AND-EXAMPLES.md).
+### Functions
+- **Text Search**
+  - Full text search (`to_tsvector`, `to_tsquery`)
+  - Pattern matching (`ILIKE`, `SIMILAR TO`)
+  - Regular expressions
+- **Array Functions**
+  - Array aggregation (`array_agg`)
+  - Array manipulation (`array_append`, `array_prepend`)
+  - Array dimensions and length
+- **JSON Functions**
+  - JSON construction (`json_build_object`, `jsonb_build_object`)
+  - JSON manipulation and transformation
+- **Date Functions**
+- **Aggregate Functions**
 
-----
-## License
-This package is licensed under the MIT License.
+Full documentation:
+- [Available Types](docs/AVAILABLE-TYPES.md)
+- [Available Functions and Operators](docs/AVAILABLE-FUNCTIONS-AND-OPERATORS.md)
+- [Common Use Cases and Examples](docs/USE-CASES-AND-EXAMPLES.md)
+
+## 📦 Installation
+
+```bash
+composer require martin-georgiev/postgresql-for-doctrine
+```
+
+## 🔧 Integration Guides
+
+- [Integrating with Symfony](docs/INTEGRATING-WITH-SYMFONY.md)
+- [Integrating with Laravel](docs/INTEGRATING-WITH-LARAVEL.md)
+- [Integrating with Doctrine](docs/INTEGRATING-WITH-DOCTRINE.md)
+
+## 💡 Usage Examples
+See our [Common Use Cases and Examples](docs/USE-CASES-AND-EXAMPLES.md) for detailed code samples.
+
+## ⭐ Support the Project
+
+### 💖 GitHub Sponsors
+If you find this package useful for your projects, please consider [sponsoring the development via GitHub Sponsors](https://github.com/sponsors/martin-georgiev). Your support helps maintain this package, create new features, and improve documentation.
+
+Benefits of sponsoring:
+- Priority support for issues and feature requests
+- Direct access to the maintainer
+- Help sustain open-source development
+
+### Other Ways to Help
+- Star the repository
+- [Report issues](https://github.com/martin-georgiev/postgresql-for-doctrine/issues)
+- [Contribute](docs/CONTRIBUTING.md) with code or documentation
+- Share the project with others
+
+## 📝 License
+This package is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

docs/CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 **Before opening your first PR**
 
-For the sake of clear Git history and speedy review of your PR please check that the suggested changes are in line with the project's standards. Code style, static analysis and file validation scripts are already provided and can easily be checked with running from project's root:
+For the sake of clear Git history and speedy review of your PR, please check that the suggested changes are in line with the project's standards. Code style, static analysis and file validation scripts are already provided and can easily be run from project's root:
 
 `composer check-code-style` which will check for consistent code style
 
@@ -33,7 +33,7 @@ For the sake of clear Git history and speedy review of your PR please check that
 
 Most new functions will likely have a signature very similar to those already implemented in the project. This means new functions probably require only extending the base class and decorating it with some behaviour. Here are the two main steps to follow:
 1. Extend `MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\BaseFunction`.
-2. Use calls to `setFunctionPrototype()` and `addNodeMapping()` to implement `customiseFunction()` for your new function class.
+2. Use calls to `setFunctionPrototype()` and `addNodeMapping()` to implement `customizeFunction()` for your new function class.
 
 Example:
 
@@ -46,7 +46,7 @@ namespace MartinGeorgiev\Doctrine\ORM\Query\AST\Functions;
 
 class ArrayAppend extends BaseFunction
 {
-    protected function customiseFunction(): void
+    protected function customizeFunction(): void
     {
         $this->setFunctionPrototype('array_append(%s, %s)');
         $this->addNodeMapping('StringPrimary'); # corresponds to param №1 in the prototype set in setFunctionPrototype

docs/USE-CASES-AND-EXAMPLES.md

@@ -1,17 +1,22 @@
 Clarification on usage of `ILIKE`, `CONTAINS`, `IS_CONTAINED_BY`, `DATE_OVERLAPS` and some other operator-like functions
 ---
 
-`Error: Expected =, <, <=, <>, >, >=, !=, got 'ILIKE'"` (or similar) is probably one of the most common DQL errors you may experience when working with this library. The cause for is that when parsing the DQL Doctrine won't recognise `ILIKE` as a known operator. In fact `ILIKE` is registered as a boolean function.
+`Error: Expected =, <, <=, <>, >, >=, !=, got 'ILIKE'"` (or similar) is probably one of the most common DQL errors you may experience when working with this library. The cause for is that when parsing the DQL Doctrine won't recognize `ILIKE` as a known operator. In fact `ILIKE` is registered as a boolean function.
 Doctrine doesn't provide easy support for implementing custom operators. This may change in the future but for now it is easier to trick the DQL parser with a boolean expression.
 
-Example intent with DQL:
+Example intent with PostgreSQL:
+```sql
+SELECT * FROM emails WHERE subject ILIKE 'Test email';
+```
+
+Intuitively, one may assume the below DQL. However it will not work:
 ```sql
 SELECT e
 FROM EmailEntity e
 WHERE e.subject ILIKE 'Test email'
 ```
 
-Boolean expression that will parse and is equivalent to the above DQL:
+The correct DQL is with a boolean expression that will parse correctly and can look like this:
 ```sql
 SELECT e
 FROM EmailEntity e

src/MartinGeorgiev/Doctrine/DBAL/Types/BaseArray.php

@@ -8,7 +8,7 @@
 use Doctrine\DBAL\Types\ConversionException;
 
 /**
- * Abstract handling of PostgreSql array data types.
+ * Abstract handling of PostgreSQL array data types.
  *
  * @see https://www.postgresql.org/docs/9.4/static/arrays.html
  * @since 0.1
@@ -18,7 +18,7 @@
 abstract class BaseArray extends BaseType
 {
     /**
-     * Converts a value from its PHP representation to its PostgreSql representation of the type.
+     * Converts a value from its PHP representation to its PostgreSQL representation of the type.
      *
      * @param array|null $phpArray the value to convert
      *
@@ -38,7 +38,7 @@ public function convertToDatabaseValue($phpArray, AbstractPlatform $platform): ?
 
         foreach ($phpArray as &$item) {
             if (!$this->isValidArrayItemForDatabase($item)) {
-                $exceptionMessage = 'One or more of items given doesn\'t look like valid.';
+                $exceptionMessage = 'One or more of the items given doesn\'t look valid.';
 
                 throw new ConversionException($exceptionMessage);
             }
@@ -49,15 +49,15 @@ public function convertToDatabaseValue($phpArray, AbstractPlatform $platform): ?
     }
 
     /**
-     * Tests if given PHP array item is from compatible type for PostgreSql.
+     * Tests if given PHP array item is from compatible type for PostgreSQL.
      */
     protected function isValidArrayItemForDatabase(mixed $item): bool
     {
         return true;
     }
 
     /**
-     * Transforms PHP array item to a PostgreSql compatible array item.
+     * Transforms PHP array item to a PostgreSQL compatible array item.
      *
      * @return mixed
      */
@@ -67,7 +67,7 @@ protected function transformArrayItemForPostgres(mixed $item)
     }
 
     /**
-     * Converts a value from its PostgreSql representation to its PHP representation of this type.
+     * Converts a value from its PostgreSQL representation to its PHP representation of this type.
      *
      * @param string|null $postgresArray the value to convert
      */
@@ -77,7 +77,7 @@ public function convertToPHPValue($postgresArray, AbstractPlatform $platform): ?
             return null;
         }
         if (!\is_string($postgresArray)) {
-            $exceptionMessage = 'Given PostgreSql value content type is not PHP string. Instead it is "%s".';
+            $exceptionMessage = 'Given PostgreSQL value content type is not PHP string. Instead it is "%s".';
 
             throw new ConversionException(\sprintf($exceptionMessage, \gettype($postgresArray)));
         }
@@ -101,7 +101,7 @@ protected function transformPostgresArrayToPHPArray(string $postgresArray): arra
     }
 
     /**
-     * Transforms PostgreSql array item to a PHP compatible array item.
+     * Transforms PostgreSQL array item to a PHP compatible array item.
      *
      * @return mixed
      */

src/MartinGeorgiev/Doctrine/DBAL/Types/BigIntArray.php

@@ -5,7 +5,7 @@
 namespace MartinGeorgiev\Doctrine\DBAL\Types;
 
 /**
- * Implementation of PostgreSql BIGINT[] data type.
+ * Implementation of PostgreSQL BIGINT[] data type.
  *
  * @see https://www.postgresql.org/docs/9.4/static/arrays.html
  * @since 0.1

src/MartinGeorgiev/Doctrine/DBAL/Types/BooleanArray.php

@@ -7,7 +7,7 @@
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 
 /**
- * Implementation of PostgreSql BOOL[] data type.
+ * Implementation of PostgreSQL BOOL[] data type.
  *
  * @see https://www.postgresql.org/docs/9.4/static/arrays.html
  * @since 1.5.3

src/MartinGeorgiev/Doctrine/DBAL/Types/Exceptions/UnexpectedTypeOfTransformedPHPValue.php

@@ -14,7 +14,7 @@ class UnexpectedTypeOfTransformedPHPValue extends TypeException
     public function __construct(string $untransformedValue, string $typeOfTransformedPHPValue)
     {
         $message = \sprintf(
-            'Transforming a PostgreSql value "%s" results to an unexpected PHP value from type "%s".',
+            'Transforming a PostgreSQL value "%s" results to an unexpected PHP value from type "%s".',
             $untransformedValue,
             $typeOfTransformedPHPValue
         );

src/MartinGeorgiev/Doctrine/DBAL/Types/IntegerArray.php

@@ -5,7 +5,7 @@
 namespace MartinGeorgiev\Doctrine\DBAL\Types;
 
 /**
- * Implementation of PostgreSql INTEGER[] data type.
+ * Implementation of PostgreSQL INTEGER[] data type.
  *
  * @see https://www.postgresql.org/docs/9.4/static/arrays.html
  * @since 0.1