feature #15858 [PropertyInfo] Import the component (dunglas)

This PR was squashed before being merged into the 2.8 branch (closes #15858).

Discussion
----------

[PropertyInfo] Import the component

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | n/a
| License       | MIT
| Doc PR        | symfony/symfony-docs#5717

As discussed with @fabpot (see #14844), this PR moves [dunglas/php-property-info](https://github.com/dunglas/php-property-info) under the Symfony umbrella.

Rationale behind this new component (extracted from README.md):

PHP doesn't support explicit type definition. This is annoying, especially when doing meta programming.
Various libraries including but not limited to Doctrine ORM and the Symfony Validator provide their own type managing
system.
This library extracts various information including the type and documentation from PHP class property from metadata of popular sources:

* Setter method with type hint
* PHPDoc DocBlock
* Doctrine ORM mapping (annotation, XML, YML or custom format)
* PHP 7 scalar typehint and return type
* Serializer metadata

**Usage:**

```php
<?php

// Use Composer autoload
require 'vendor/autoload.php';

use Doctrine\ORM\EntityManager;
use Doctrine\ORM\Tools\Setup;
use Doctrine\ORM\Mapping\Column;
use Doctrine\ORM\Mapping\Entity;
use Doctrine\ORM\Mapping\Id;
use Symfony\Component\PropertyInfo\Extractors\DoctrineExtractor;
use Symfony\Component\PropertyInfo\Extractors\PhpDocExtractor;
use Symfony\Component\PropertyInfo\Extractors\ReflectionExtractor;
use Symfony\Component\PropertyInfo\PropertyInfo;

/**
 * @entity
 */
class MyTestClass
{
    /**
     * @id
     * @column(type="integer")
     */
    public $id;
    /**
     * This is a date (short description).
     *
     * With a long description.
     *
     * @var \DateTime
     */
    public $foo;
    private $bar;

    public function setBar(\SplFileInfo $bar)
    {
        $this->bar = $bar;
    }
}

// Doctrine initialization (necessary only to use the Doctrine Extractor)
$config = Setup::createAnnotationMetadataConfiguration([__DIR__], true);
$entityManager = EntityManager::create([
    'driver' => 'pdo_sqlite',
    // ...
], $config);

$doctrineExtractor = new DoctrineExtractor($entityManager->getMetadataFactory());
$phpDocExtractor = new PhpDocExtractor();
$reflectionExtractor = new ReflectionExtractor();

$propertyInfo = new PropertyInfo(
    array($reflectionExtractor),
    array($doctrineExtractor, $phpDocExtractor, $reflectionExtractor),
    array($phpDocExtractor),
    array($reflectionExtractor)
);

var_dump($propertyInfo->getProperties('MyTestClass'));
var_dump($propertyInfo->getTypes('MyTestClass', 'foo'));
var_dump($propertyInfo->getTypes('MyTestClass', 'id'));
var_dump($propertyInfo->getTypes('MyTestClass', 'bar'));
var_dump($propertyInfo->isReadable('MyTestClass', 'id'));
var_dump($propertyInfo->isReadable('MyTestClass', 'bar'));
var_dump($propertyInfo->isWritable('MyTestClass', 'foo'));
var_dump($propertyInfo->isWritable('MyTestClass', 'bar'));
var_dump($propertyInfo->getShortDescription('MyTestClass', 'foo'));
var_dump($propertyInfo->getLongDescription('MyTestClass', 'foo'));
```

Output:

```
array(3) {
  [0] =>
  string(2) "id"
  [1] =>
  string(3) "foo"
  [2] =>
  string(3) "Bar"
}
array(1) {
  [0] =>
  class Symfony\Component\PropertyInfo\Type#36 (6) {
    private $builtinType =>
    string(6) "object"
    private $nullable =>
    bool(false)
    private $class =>
    string(8) "DateTime"
    private $collection =>
    bool(false)
    private $collectionKeyType =>
    NULL
    private $collectionValueType =>
    NULL
  }
}
array(1) {
  [0] =>
  class Symfony\Component\PropertyInfo\Type#36 (6) {
    private $builtinType =>
    string(3) "int"
    private $nullable =>
    bool(false)
    private $class =>
    NULL
    private $collection =>
    bool(false)
    private $collectionKeyType =>
    NULL
    private $collectionValueType =>
    NULL
  }
}
array(1) {
  [0] =>
  class Symfony\Component\PropertyInfo\Type#245 (6) {
    private $builtinType =>
    string(6) "object"
    private $nullable =>
    bool(false)
    private $class =>
    string(11) "SplFileInfo"
    private $collection =>
    bool(false)
    private $collectionKeyType =>
    NULL
    private $collectionValueType =>
    NULL
  }
}
bool(true)
bool(false)
bool(true)
bool(true)
string(35) "This is a date (short description)."
string(24) "With a long description."
```

Commits
-------

f1eb185 [PropertyInfo] Import the component

Author: fabpot

composer.json

@@ -48,6 +48,7 @@
         "symfony/options-resolver": "self.version",
         "symfony/process": "self.version",
         "symfony/property-access": "self.version",
+        "symfony/property-info": "self.version",
         "symfony/proxy-manager-bridge": "self.version",
         "symfony/routing": "self.version",
         "symfony/security": "self.version",
@@ -76,7 +77,11 @@
         "monolog/monolog": "~1.11",
         "ircmaxell/password-compat": "~1.0",
         "ocramius/proxy-manager": "~0.4|~1.0",
-        "egulias/email-validator": "~1.2"
+        "egulias/email-validator": "~1.2",
+        "phpdocumentor/reflection": "^1.0.7"
+    },
+    "conflict": {
+        "phpdocumentor/reflection": "<1.0.7"
     },
     "autoload": {
         "psr-4": {

src/Symfony/Bridge/Doctrine/PropertyInfo/DoctrineExtractor.php

@@ -0,0 +1,149 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bridge\Doctrine\PropertyInfo;
+
+use Doctrine\Common\Persistence\Mapping\ClassMetadataFactory;
+use Doctrine\Common\Persistence\Mapping\MappingException;
+use Doctrine\ORM\Mapping\ClassMetadataInfo;
+use Symfony\Component\PropertyInfo\PropertyListExtractorInterface;
+use Symfony\Component\PropertyInfo\PropertyTypeExtractorInterface;
+use Symfony\Component\PropertyInfo\Type;
+
+/**
+ * Extracts data using Doctrine ORM and ODM metadata.
+ *
+ * @author Kévin Dunglas <dunglas@gmail.com>
+ */
+class DoctrineExtractor implements PropertyListExtractorInterface, PropertyTypeExtractorInterface
+{
+    /**
+     * @var ClassMetadataFactory
+     */
+    private $classMetadataFactory;
+
+    public function __construct(ClassMetadataFactory $classMetadataFactory)
+    {
+        $this->classMetadataFactory = $classMetadataFactory;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getProperties($class, array $context = array())
+    {
+        try {
+            $metadata = $this->classMetadataFactory->getMetadataFor($class);
+        } catch (MappingException $exception) {
+            return;
+        }
+
+        return array_merge($metadata->getFieldNames(), $metadata->getAssociationNames());
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getTypes($class, $property, array $context = array())
+    {
+        try {
+            $metadata = $this->classMetadataFactory->getMetadataFor($class);
+        } catch (MappingException $exception) {
+            return;
+        }
+
+        if ($metadata->hasAssociation($property)) {
+            $class = $metadata->getAssociationTargetClass($property);
+
+            if ($metadata->isSingleValuedAssociation($property)) {
+                if ($metadata instanceof ClassMetadataInfo) {
+                    $nullable = isset($metadata->discriminatorColumn['nullable']) ? $metadata->discriminatorColumn['nullable'] : false;
+                } else {
+                    $nullable = false;
+                }
+
+                return array(new Type(Type::BUILTIN_TYPE_OBJECT, $nullable, $class));
+            }
+
+            return array(new Type(
+                Type::BUILTIN_TYPE_OBJECT,
+                false,
+                'Doctrine\Common\Collections\Collection',
+                true,
+                new Type(Type::BUILTIN_TYPE_INT),
+                new Type(Type::BUILTIN_TYPE_OBJECT, false, $class)
+            ));
+        }
+
+        if ($metadata->hasField($property)) {
+            $typeOfField = $metadata->getTypeOfField($property);
+            $nullable = $metadata instanceof ClassMetadataInfo && $metadata->isNullable($property);
+
+            switch ($typeOfField) {
+                case 'date':
+                case 'datetime':
+                case 'datetimetz':
+                case 'time':
+                    return array(new Type(Type::BUILTIN_TYPE_OBJECT, $nullable, 'DateTime'));
+
+                case 'array':
+                    return array(new Type(Type::BUILTIN_TYPE_ARRAY, $nullable, null, true));
+
+                case 'simple_array':
+                    return array(new Type(Type::BUILTIN_TYPE_ARRAY, $nullable, null, true, new Type(Type::BUILTIN_TYPE_INT), new Type(Type::BUILTIN_TYPE_STRING)));
+
+                case 'json_array':
+                    return array(new Type(Type::BUILTIN_TYPE_ARRAY, $nullable, null, true));
+
+                default:
+                    return array(new Type($this->getPhpType($typeOfField), $nullable));
+            }
+        }
+    }
+
+    /**
+     * Gets the corresponding built-in PHP type.
+     *
+     * @param string $doctrineType
+     *
+     * @return string
+     */
+    private function getPhpType($doctrineType)
+    {
+        switch ($doctrineType) {
+            case 'smallint':
+                // No break
+            case 'bigint':
+                // No break
+            case 'integer':
+                return Type::BUILTIN_TYPE_INT;
+
+            case 'decimal':
+                return Type::BUILTIN_TYPE_FLOAT;
+
+            case 'text':
+                // No break
+            case 'guid':
+                return Type::BUILTIN_TYPE_STRING;
+
+            case 'boolean':
+                return Type::BUILTIN_TYPE_BOOL;
+
+            case 'blob':
+                // No break
+            case 'binary':
+                return Type::BUILTIN_TYPE_RESOURCE;
+
+            default:
+                return $doctrineType;
+        }
+    }
+}

src/Symfony/Bridge/Doctrine/Tests/PropertyInfo/DoctrineExtractorTest.php

@@ -0,0 +1,84 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bridge\Doctrine\PropertyInfo\Tests;
+
+use Doctrine\ORM\EntityManager;
+use Doctrine\ORM\Tools\Setup;
+use Symfony\Bridge\Doctrine\PropertyInfo\DoctrineExtractor;
+use Symfony\Component\PropertyInfo\Type;
+
+/**
+ * @author Kévin Dunglas <dunglas@gmail.com>
+ */
+class DoctrineExtractorTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @var DoctrineExtractor
+     */
+    private $extractor;
+
+    public function setUp()
+    {
+        $config = Setup::createAnnotationMetadataConfiguration(array(__DIR__.DIRECTORY_SEPARATOR.'Fixtures'), true);
+        $entityManager = EntityManager::create(array('driver' => 'pdo_sqlite'), $config);
+
+        $this->extractor = new DoctrineExtractor($entityManager->getMetadataFactory());
+    }
+
+    public function testGetProperties()
+    {
+        $this->assertEquals(
+             array(
+                'id',
+                'guid',
+                'time',
+                'json',
+                'simpleArray',
+                'bool',
+                'binary',
+                'foo',
+                'bar',
+            ),
+            $this->extractor->getProperties('Symfony\Bridge\Doctrine\Tests\PropertyInfo\Fixtures\DoctrineDummy')
+        );
+    }
+
+    /**
+     * @dataProvider typesProvider
+     */
+    public function testExtract($property, array $type = null)
+    {
+        $this->assertEquals($type, $this->extractor->getTypes('Symfony\Bridge\Doctrine\Tests\PropertyInfo\Fixtures\DoctrineDummy', $property, array()));
+    }
+
+    public function typesProvider()
+    {
+        return array(
+            array('id', array(new Type(Type::BUILTIN_TYPE_INT))),
+            array('guid', array(new Type(Type::BUILTIN_TYPE_STRING))),
+            array('bool', array(new Type(Type::BUILTIN_TYPE_BOOL))),
+            array('binary', array(new Type(Type::BUILTIN_TYPE_RESOURCE))),
+            array('json', array(new Type(Type::BUILTIN_TYPE_ARRAY, false, null, true))),
+            array('foo', array(new Type(Type::BUILTIN_TYPE_OBJECT, false, 'Symfony\Bridge\Doctrine\Tests\PropertyInfo\Fixtures\DoctrineRelation'))),
+            array('bar', array(new Type(
+                Type::BUILTIN_TYPE_OBJECT,
+                false,
+                'Doctrine\Common\Collections\Collection',
+                true,
+                new Type(Type::BUILTIN_TYPE_INT),
+                new Type(Type::BUILTIN_TYPE_OBJECT, false, 'Symfony\Bridge\Doctrine\Tests\PropertyInfo\Fixtures\DoctrineRelation')
+            ))),
+            array('simpleArray', array(new Type(Type::BUILTIN_TYPE_ARRAY, false, null, true, new Type(Type::BUILTIN_TYPE_INT), new Type(Type::BUILTIN_TYPE_STRING)))),
+            array('notMapped', null),
+        );
+    }
+}

src/Symfony/Bridge/Doctrine/Tests/PropertyInfo/Fixtures/DoctrineDummy.php

@@ -0,0 +1,74 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bridge\Doctrine\Tests\PropertyInfo\Fixtures;
+
+use Doctrine\ORM\Mapping\Column;
+use Doctrine\ORM\Mapping\Entity;
+use Doctrine\ORM\Mapping\Id;
+use Doctrine\ORM\Mapping\ManyToMany;
+use Doctrine\ORM\Mapping\ManyToOne;
+
+/**
+ * @Entity
+ *
+ * @author Kévin Dunglas <dunglas@gmail.com>
+ */
+class DoctrineDummy
+{
+    /**
+     * @Id
+     * @Column(type="smallint")
+     */
+    public $id;
+
+    /**
+     * @ManyToOne(targetEntity="DoctrineRelation")
+     */
+    public $foo;
+
+    /**
+     * @ManyToMany(targetEntity="DoctrineRelation")
+     */
+    public $bar;
+
+    /**
+     * @Column(type="guid")
+     */
+    protected $guid;
+
+    /**
+     * @Column(type="time")
+     */
+    private $time;
+
+    /**
+     * @Column(type="json_array")
+     */
+    private $json;
+
+    /**
+     * @Column(type="simple_array")
+     */
+    private $simpleArray;
+
+    /**
+     * @Column(type="boolean")
+     */
+    private $bool;
+
+    /**
+     * @Column(type="binary")
+     */
+    private $binary;
+
+    public $notMapped;
+}

src/Symfony/Bridge/Doctrine/Tests/PropertyInfo/Fixtures/DoctrineRelation.php

@@ -0,0 +1,29 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bridge\Doctrine\Tests\PropertyInfo\Fixtures;
+
+use Doctrine\ORM\Mapping\Column;
+use Doctrine\ORM\Mapping\Id;
+
+/**
+ * @Entity
+ *
+ * @author Kévin Dunglas <dunglas@gmail.com>
+ */
+class DoctrineRelation
+{
+    /**
+     * @Id
+     * @Column(type="smallint")
+     */
+    public $id;
+}

src/Symfony/Bridge/Doctrine/composer.json

@@ -26,6 +26,7 @@
         "symfony/form": "~2.8|~3.0.0",
         "symfony/http-kernel": "~2.2|~3.0.0",
         "symfony/property-access": "~2.3|~3.0.0",
+        "symfony/property-info": "~2.8|3.0",
         "symfony/security": "~2.2|~3.0.0",
         "symfony/expression-language": "~2.2|~3.0.0",
         "symfony/validator": "~2.5,>=2.5.5|~3.0.0",
@@ -37,6 +38,7 @@
     "suggest": {
         "symfony/form": "",
         "symfony/validator": "",
+        "symfony/property-info": "",
         "doctrine/data-fixtures": "",
         "doctrine/dbal": "",
         "doctrine/orm": ""