Add return shape for Throwable::getTrace

[ciaranmcnulty]

This is based on the documentation for debug-backtrace:
https://php.net/debug_backtrace

Experimentation that shows the object field is not populated for exceptions:
https://3v4l.org/iQoni

And validation on psalm.dev:
https://psalm.dev/r/b35a8df2f3

Should I also update the stubs?
What tests should I add?

[psalm-github-bot]

I found these snippets:

https://psalm.dev/r/b35a8df2f3

<?php

/**
 * @psalm-type Backtrace list<array{file:string,line:int,function:string,class?:string,type?:'::'|'->',args:array<mixed>}>
 */

/**
 * From:
 *
 * class cls
 * {
 *     public static function meth(int $a, string $b) : void
 *     {
 *         throw new Exception;   
 *     }
 * }
 *
 * @return Backtrace
 */
function traceWhenInsideStaticMethod()
{
    return array (
  		0 => 
  			array (
    			'file' => '/in/9n6qW',
    			'line' => 12,
    			'function' => 'meth',
    			'class' => 'cls',
    			'type' => '::',
    			'args' => 
    			array (
      				0 => 1,
      				1 => 'hello',
    				),
  			),
		);
}


/**
 * From:
 *
 * class cls
 * {
 *     public function meth2(int $a, string $b) : void
 *     {
 *         throw new Exception;   
 *     }
 * }
 *
 * @return Backtrace
 */
function traceWhenInsideObjectMethod()
{
    return array (
      0 => 
      array (
        'file' => '/in/iQoni',
        'line' => 24,
        'function' => 'meth2',
        'class' => 'cls',
        'type' => '->',
        'args' => 
        array (
          0 => 1,
          1 => 'hello',
        ),
      ),
    );
}

/**
 * From:
 *
 * function func()
 * {
 *   throw new Exception;   
 * }
 *
 * @return Backtrace
 */
function traceWhenInsideFunction()
{
    return array (
  		0 => 
  			array (
    			'file' => '/in/2cEkb',
    			'line' => 22,
    			'function' => 'func',
    			'args' => 
    		array (
    		),
  		),
	);
}


/**
 * From:
 *
 * (function() { throw new Exception;})();
 *
 * @return Backtrace
 */
/**
 * From:
 *
 * (function() { throw new Exception;})();
 *
 * @return Backtrace
 */
function traceWhenInsideAnonymousFuncion()
{
    return array (
      0 => 
      array (
        'file' => '/in/QlGeB',
        'line' => 38,
        'function' => '{closure}',
        'args' => 
        array (
        ),
      ),
    );
}

/**
 * From:
 *
 * throw new Exception;
 *
 * @return Backtrace
 */
function traceWhenInGlobalScope()
{
    return array (
    );
}

Psalm output (using commit a9f4148):

No issues!

[ciaranmcnulty]

Updated to allow optional args (in the case of an included file)

https://psalm.dev/r/11247acbc9

[psalm-github-bot]

I found these snippets:

https://psalm.dev/r/11247acbc9

<?php

/**
 * @psalm-type Backtrace list<array{file:string,line:int,function?:string,class?:string,type?:'::'|'->',args?:array<mixed>}>
 */

/**
 * From:
 *
 * class cls
 * {
 *     public static function meth(int $a, string $b) : void
 *     {
 *         throw new Exception;   
 *     }
 * }
 *
 * @return Backtrace
 */
function traceWhenInsideStaticMethod()
{
    return array (
  		0 => 
  			array (
    			'file' => '/in/9n6qW',
    			'line' => 12,
    			'function' => 'meth',
    			'class' => 'cls',
    			'type' => '::',
    			'args' => 
    			array (
      				0 => 1,
      				1 => 'hello',
    				),
  			),
		);
}


/**
 * From:
 *
 * class cls
 * {
 *     public function meth2(int $a, string $b) : void
 *     {
 *         throw new Exception;   
 *     }
 * }
 *
 * @return Backtrace
 */
function traceWhenInsideObjectMethod()
{
    return array (
      0 => 
      array (
        'file' => '/in/iQoni',
        'line' => 24,
        'function' => 'meth2',
        'class' => 'cls',
        'type' => '->',
        'args' => 
        array (
          0 => 1,
          1 => 'hello',
        ),
      ),
    );
}

/**
 * From:
 *
 * function func()
 * {
 *   throw new Exception;   
 * }
 *
 * @return Backtrace
 */
function traceWhenInsideFunction()
{
    return array (
  		0 => 
  			array (
    			'file' => '/in/2cEkb',
    			'line' => 22,
    			'function' => 'func',
    			'args' => 
    		array (
    		),
  		),
	);
}


/**
 * From:
 *
 * (function() { throw new Exception;})();
 *
 * @return Backtrace
 */
/**
 * From:
 *
 * (function() { throw new Exception;})();
 *
 * @return Backtrace
 */
function traceWhenInsideAnonymousFuncion()
{
    return array (
      0 => 
      array (
        'file' => '/in/QlGeB',
        'line' => 38,
        'function' => '{closure}',
        'args' => 
        array (
        ),
      ),
    );
}

/**
 * From:
 *
 * throw new Exception;
 *
 * @return Backtrace
 */
function traceWhenInGlobalScope()
{
    return array (
    );
}

/**
 * From:
 *
 * throw new Exception;
 *
 * @return Backtrace
 */
function traceWhenInInclude()
{
    return array (
      0 => array (
        'file' => '/Users/ciaranmcnulty/Code/composer-scratch-test/test.php',
        'line' => 3,
        'function' => 'include',
      ),
    );
}

Psalm output (using commit a9f4148):

No issues!

[orklah]

Seems great!

You'll have to change Callmap_Historical too for tests to pass

[ciaranmcnulty]

@orklah should I update /stubs too? I'm not sure the connection between the two things

[AndrolGenhald]

Yes, stubs should be updated too. CallMap is there because it's much faster to parse for simple functions, but stubs exist to add annotations that don't work in the CallMap, so the stubs override the CallMap. It looks like CoreImmutableClasses.phpstub is the only stub that needs changed?

[orklah]

Note: you made a PR on master, it means it will be released as a part of Psalm 5 in the near future. If it's important to you to get this quickly, you may want to rebase your PR onto 4.x so it can be released faster

[ciaranmcnulty]

I rebased onto 4.x

I'm not sure what's happened there with Appveyor?

[ciaranmcnulty]

Closed/reopened to try and nudge appveyor :/

[orklah]

Appveyor was removed from our CI ages ago, but sometimes on rebase it pops again, not sure why. As long as the rest of the CI runs, it's good

[orklah]

Thanks!

[staabm]

per phpstan/phpstan-src#914 (comment) file is optional

[staabm]

and class can be narrowed to class-string.

let me steal this more precise type-union-type into phpstan ;)

[AndrolGenhald]

line is optional as well apparently.