dunglas / phpdoc-to-typehint Goto Github PK

Add scalar type hints and return types to existing PHP projects using PHPDoc annotations

Home Page: https://dunglas.fr/2015/11/introducing-the-phpdoc-to-typehint-converter-add-scalar-type-hints-and-return-type-declarations-to-your-projects/

License: MIT License

PHP 100.00%

php php-7 phpdoc cs coding-standards

phpdoc-to-typehint's Introduction

PHPDoc to Type Hint

Archived! This repository is now archived. Consider using PHP CS Fixer (and especially the phpdoc_to_param_type and phpdoc_to_return_type rules) or Rector instead.

phpdoc-to-typehint adds automatically scalar type hints and return types to all functions and methods of a PHP project using existing PHPDoc annotations.

Warning: this project is an early stage of development. It can damage your code. Be sure to make a backup before running this command and to run your test suite after.

Please report any bug you find using this tool.

Install and usage

Download the latest PHAR file
Run php phpdoc-to-typehint.phar <your-project-directory>

Your project should have scalar type hints and return type declarations.

Before:

<?php

/**
 * @param int|null $a
 * @param string   $b
 *
 * @return float
 */
function bar($a, $b, bool $c, callable $d = null)
{
    return 0.0;
}

After:

<?php

/**
 * @param int|null $a
 * @param string   $b
 *
 * @return float
 */
function bar(int $a = null, string $b, bool $c, callable $d = null) : float
{
    return 0.0;
}

Features

Supports:

functions
methods of classes and traits
method definitions in interfaces
PHPDoc inheritance
PHP 7.1 nullable types (can be disabled with --no-nullable-types option)

Credits

Created by Kévin Dunglas. Sponsored by Les-Tilleuls.coop.

phpdoc-to-typehint's People

Contributors

Stargazers

Watchers

Forkers

meyerbaptiste kfreiman dann95 kocherovf oskarstark romainneutron playaer mhujer hboomsma cjhoffice ricordisamoa miguelgf staabm lyrixx theofidry gregoirehebert kazualex

phpdoc-to-typehint's Issues

Example in readme is invalid

I don't think it is correct to generate code which will put an argument with a default value before an argument without a default value.

In the example the generated code produces a function like that:

function bar(int $a = null, string $b, bool $c, callable $d = null) : float

This means the first argument is optional, but the second and third aren't.

I realise = null is the only way in PHP before 7.1 to specify a type-hinted argument could also be null, but generating such code I think is incorrect.

My suggestion is to never make a parameter without a default value to have one.

When PHP 7.1 is available - #16, the example could be using ?int which would be correct.

First paramert is ofthen not hinted

Before

    /**
     * The copy the specified message(s) to a specified mailbox.
     *
     * @param string $msgSet  Message(s) to fetch
     * @param string $mailbox Name of mailbox to copy messages to
     * @param bool   $uid     Weather to use UID
     *
     * @return array Raw from responce()
     */
    public function copy($msgSet, $mailbox, $uid = false)
    {
    }

after

    /**
     * The copy the specified message(s) to a specified mailbox.
     *
     * @param string $msgSet  Message(s) to fetch
     * @param string $mailbox Name of mailbox to copy messages to
     * @param bool   $uid     Weather to use UID
     *
     * @return array Raw from responce()
     */
    public function copy($msgSet, string $mailbox, bool $uid = false): array
    {
    }

Possible to run on single file

Some times it would be helpfull to be able to run the program on just a single file, especially when trying to fix a parsing issues with a specific file, it would be nice to skip analyzing all other files in the folder.

InvalidArgumentException at @see

/**
* @see http://swiftmailer.org
*/

throws

  [InvalidArgumentException]                                       
  "\yii\swiftmailer\http://swiftmailer.org" is not a valid Fqsen.

Support PHP7.1

Hello,

Are there any plans to support PHP7.1 new type declarations and nullable types? Example:

function returnsNothing(iterable $iterable, ?string $nullableString): void {
...
}

Aliased classes in return statements are not mantained when ported to PHP7

Problem is, it will resolve the original class and write the FQN instead of keeping the Alias.

This leads to namespace collisions.

By reference is applied in correctly

/**
 * @param array $array
 */
function test(&$array) {}

Becomes

/**
 * @param array $array
 */
function test(&array $array) {}

Should have been

/**
 * @param array $array
 */
function test(array &$array) {}

Add a dry run mode

Use https://github.com/sebastianbergmann/diff to add a --dry-run option not modifying the files but returning a diff.

Constant visibility is not supported

Code like this:

class Foo
{
	public const BAR = 1;
}

produces the following error:

[PhpParser\Error]
  Syntax error, unexpected T_CONST, expecting T_FUNCTION on line 16

This is valid code in PHP 7.1.

@see is mistaken for a type

The following class instance variable:

    /**
     * If you’ve enabled user specific timezones, you may set or update the
     * user timezone.
     * @see https://docs.looker.com/reference/embedding/timezones
     * @var string|null
     */
    public $userTimeZone = null;

Produces the error:

  [InvalidArgumentException]
  "\Kounta\Insights\Looker\https://docs.looker.com/reference/embedding/timezones" is not a valid Fqsen.

Cannot ue 'Void' as class name

using the latest release v.0.1.0 I am running into the following error

$ php phpdoc-to-typehint.phar .
PHP Fatal error:  Cannot use 'Void' as class name as it is reserved in phar://C:
/Users/mstaab/Documents/GitHub/deployer/phpdoc-to-typehint.phar/vendor/phpdocume
ntor/type-resolver/src/Types/Void.php on line 23

Fatal error: Cannot use 'Void' as class name as it is reserved in phar://C:/User
s/mstaab/Documents/GitHub/deployer/phpdoc-to-typehint.phar/vendor/phpdocumentor/
type-resolver/src/Types/Void.php on line 23

seems like the downloaded phar is unusable to run on php7.1+

$ php -v
PHP 7.1.2 (cli) (built: Feb 14 2017 21:24:45) ( NTS MSVC14 (Visual C++ 2015) x64 )
Copyright (c) 1997-2017 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2017 Zend Technologies

php 7.1: requirements could not be resolved to an installable set of packages

atm I cannot install this tool via composer

C:\Users\mstaab>composer global require dunglas/phpdoc-to-typehint
Changed current directory to C:/Users/mstaab/AppData/Roaming/Composer
Using version ^0.1.0 for dunglas/phpdoc-to-typehint
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)

Failed to decode response: zlib_decode(): data error
Retrying with degraded mode, check https://getcomposer.org/doc/articles/troubleshooting.md#degraded-mode for more info
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Installation request for dunglas/phpdoc-to-typehint ^0.1.0 -> satisfiable by dunglas/phpdoc-to-typehint[v0.1.0].
    - dunglas/phpdoc-to-typehint v0.1.0 requires phpdocumentor/reflection ^2.0@dev -> satisfiable by phpdocumentor/reflection[2.0.0-alpha1, 2.0.0-alpha2] but these conflict with your requirements or minimum-stability.


Installation failed, reverting ./composer.json to its original content.

C:\Users\mstaab>php -v
PHP 7.1.2 (cli) (built: Feb 14 2017 21:24:45) ( NTS MSVC14 (Visual C++ 2015) x64 )
Copyright (c) 1997-2017 The PHP Group
Zend Engine v3.1.0, Copyright (c) 1998-2017 Zend Technologies

any chance to get rid of this @dev dependencies in composer.json so we composer can make a more educated dependency resolution?

Nullable type hints in existing code break the parser

Signatures like these below break the parser:

function(?Foo $foo) {}

function(): ?Foo {}

RFC: Do not change method signature when this would break inheritance

If the function is overriding a parent method there are limitations to changing the method signature. Future PHP versions could improve that with more support for Covariance and Contravariance, but there are still cases where signatures could not blindly be changed.

If the PHPDoc to typehints conversion take this into account and don't change things which would produce a direct PHP error it would be less risky and could be deployed more widely. It could even work in a CI environment.

Error doesn't point to file and line that is at fault

/**
 * @return
 */

/**
 * @var
 */

Will result in the following error:

  [InvalidArgumentException]           
  Expected a non-empty value. Got: ""

It is tedious to tract down the file and line to solve the issue. Theas specific phpdoc errors could probably be skiped, but the issue is the same if the value is "boolean;", "mixed", some other incorrect value.

Validation errors do give a line number but with out a file it is mostly useless:

  [PhpParser\Error]                                                  
  Syntax error, unexpected T_ARRAY, expecting T_VARIABLE on line 62