Documentation for type descriptors

Author: lookyman

README.md

@@ -17,6 +17,7 @@ This extension provides following features:
 * Provides correct return type for `Doctrine\ORM\EntityManager::find`, `getReference` and `getPartialReference` when `Foo::class` entity class name is provided as the first argument
 * Adds missing `matching` method on `Doctrine\Common\Collections\Collection`. This can be turned off by setting `parameters.doctrine.allCollectionsSelectable` to `false`.
 * Also supports Doctrine ODM.
+* Analysis of discrepancies between entity column types and property field types.
 
 ## Installation
 
@@ -73,3 +74,46 @@ $kernel = new Kernel($_SERVER['APP_ENV'], (bool) $_SERVER['APP_DEBUG']);
 $kernel->boot();
 return $kernel->getContainer()->get('doctrine')->getManager();
 ```
+
+## Custom types
+
+If your application uses custom Doctrine types, you can write your own type descriptors to analyse them properly.
+Type descriptors implement the interface `PHPStan\Type\Doctrine\Descriptors\DoctrineTypeDescriptor` which looks like this:
+
+```php
+public function getType(): string;
+
+public function getWritableToPropertyType(): Type;
+
+public function getWritableToDatabaseType(): Type;
+```
+
+* The `getType()` method simply returns the name of the custom type.
+* The `getWritableToPropertyType()` method returns the PHPStan type that the custom type will write into the entity's property field. Basically it is the return type of the custom type's `convertToPHPValue()` method.
+* The `getWritableToDatabaseType()` method returns the PHPStan type that can be written from the entity's property field into the custom type. Again, basically it's the allowed type for the custom type's `convertToDatabaseValue()`'s first argument.
+
+Generally, at least for most of Doctrine's native types, these last two methods will return the same type, but it is not always the case. One example would be the `datetime` type, which allows you to set any `\DateTimeInterface` into to property field, but will always contain the `\DateTime` type when loaded from the database.
+
+### Nullable types
+
+Type descriptors don't have to deal with nullable types, as these are transparently added/removed from the descriptor's types as needed. Therefore you don't have to return the union type of your custom type and `NullType` from the descriptor's methods, even if your custom type allows `null`.
+
+### ReflectionDescriptor
+
+If your custom type's `convertToPHPValue()` and `convertToDatabaseValue()` methods have proper typehints, you don't have to write your own descriptor for it. The `PHPStan\Type\Doctrine\Descriptors\ReflectionDescriptor` can analyse the typehints and do the rest for you.
+
+### Registering type descriptors
+
+When you write a custom type descriptor, you have to let PHPStan know about it. Add something like this into your `phpstan.neon`:
+
+```neon
+services:
+	-
+		class: MyCustomTypeDescriptor
+		tags: [phpstan.doctrine.typeDescriptor]
+
+	# in case you are using the ReflectionDescriptor
+	-
+		class: PHPStan\Type\Doctrine\Descriptors\ReflectionDescriptor('my_custom_type_name')
+		tags: [phpstan.doctrine.typeDescriptor]
+```