Improved preg_match() output param type inference

[rarila]

This PR adds a stub for preg_match() that takes flags into account.
Fixes #6914

For reference:

• Return Values

  • 1 if the pattern matches given subject
  • 0 if the pattern does not match given subject
  • false on failure

• $matches with flag: 0

  preg_match('/(foo)(not)?(?<name>bar)/', 'foobarbaz', $matches);

  $matches:

  [
    0      => 'foobar',
    1      => 'foo',
    2      => '',
    'name' => 'bar',
    3      => 'bar',
  ]
  

  ➡️ array<array-key, string>

• $matches with flag: PREG_OFFSET_CAPTURE = 256

  preg_match('/(foo)(not)?(?<name>bar)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);

  $matches:

  [
    0      => [0 => 'foobar', 1 =>  0],
    1      => [0 => 'foo',    1 =>  0],
    2      => [0 => '',       1 => -1],
    'name' => [0 => 'bar',    1 =>  3],
    3      => [0 => 'bar',    1 =>  3],
  ]
  

  ➡️ array<array-key, array{string, 0|positive-int}|array{'', -1}>
  ↪️ array<array-key, array{string, int}>

• $matches with flag: PREG_UNMATCHED_AS_NULL = 512

  preg_match('/(foo)(not)?(?<name>bar)/', 'foobarbaz', $matches, PREG_UNMATCHED_AS_NULL);

  $matches:

  [
    0      => 'foobar',
    1      => 'foo',
    2      => null,
    'name' => 'bar',
    3      => 'bar',
  ]
  

  ➡️ array<array-key, string|null>

• $matches with flag: PREG_OFFSET_CAPTURE | PREG_UNMATCHED_AS_NULL = 768

  preg_match('/(foo)(not)?(?<name>bar)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE | PREG_UNMATCHED_AS_NULL);

  $matches:

  [
    0      => [0 => 'foobar', 1 =>  0],
    1      => [0 => 'foo',    1 =>  0],
    2      => [0 => null,     1 => -1],
    'name' => [0 => 'bar',    1 =>  3],
    3      => [0 => 'bar',    1 =>  3],
  ]
  

  ➡️ array<array-key, array{string, 0|positive-int}|array{null, -1}>
  ↪️ array<array-key, array{null|string, int}>

• $matches on error
  On error an E_WARNING is emitted. $matches is not altered then. This case is not handled in this PR.

Legend:
↪️ = expression simplified by Psalm

[weirdan]

Thanks!