The phpdoc array keys format supported by the plugin.

[klesun]

The README briefly mentions an ability to specify array keys in a doc. I'll describe it a bit more detailed here...

So, basically, in the @param, @var, @property, @method and @return phpdoc tags, after the variable name, you can type an = followed by any valid php expression - it will be parsed by the plugin and used in completion on further references to this variable.

• Example: (specify that var contains the value returned by a function)

  /**
   * @param $sale = self::createSale() // a sale confirmed by bookeeping
   */
  public function processSale($sale) {}

  

• Another example: (specify associative array keys)

  /** @var array $clientData = [
   *     'id' => 1234, // unique id in DB
   *     'activityDt' => new DateTime,
   *     'sales' => [SaleApp::createSale()], // array of one or more sales client had with us over the years
   *     'agentReviews' => [
   *          ['agent' => 'Steeve', 'rating' => 9.5, 'comment' => 'Does his job well'],
   *          ['agent' => 'Tiffany', 'rating' => 6.3, 'comment' => 'Could try harder'],
   *     ],
   *     'soapData' => (object)[ // the data we got from external system
   *         'LoanPast' => 'GOOD',
   *         'Job' => 'WEB DESIGNER',
   *     ],
   * ] */
  $clientData = json_decode($text, true);

  

• Note that these type annotation will also work for argument key completion when you are calling the function:

  

• Another example: (specify return type keys)

  /** @return array [
   *     'address' => 'Novokuzneckaya Oblastj, Dom 427, Moscow, Russia',
   *     'family' => 'single',
   *     'name' => 'Vasya Pupkin',
   * ] */
  private function getExternalData() {}

  
  (an = between @return and the expression is allowed, but not required)

• As discussed in Enumeration #50, you can specify "enum" string value options in phpdoc:

  /** @param $parameters = ['keyword1', 'keyword2', 'keyword3'][$any] */
  function my_test($parameters) {}

  

• As mentioned below, you can specify magic method return type like that:

   * @method array getData() = ['name' => 'John', 'age' => 27]
  

• As described in centralize configure as similar as .phpstorm.meta.php of phpstorm #75, you can now specify function return type and it's argument types in .phpstorm.meta.php

  

• As described in Support PSALM/phan phpdoc notation #77, you can now use psalm/phan array{key1: int, key2: string} notation to specify key types (with @template generics, yay)

  

• As described in Implement WordPress-like documentations // Magic::argType() #152, you can now use WordPress format notation to specify key types

  

• As described in Twig type hints don't seem to work with completion for me #165 and Allow to specify php data reference function FQN in twig comment #119, deep-assoc also allows you to reference functions by fully qualified name in Twig templates to use them as type information for vars completion:

  Considering we have such php class somewhere in the project:

   namespace SomeNamespace;
   class SomeClass {
   	private function makeTemplateData() {
   		return [
   			'userName' => 'Vasya', 
   			'paymentMethods' => [
   				['name' => 'Paypal', 'countries' => ['US', 'LV']],
   				['name' => 'Swedbank', 'countries' => ['ES', 'LV']],
   			],
   		];
   	}
   }

  You can reference it in a twig file with {# data-source = ... #}:

   {# data-source = \SomeNamespace\SomeClass::makeTemplateData() #}
  
   <div>
   	<span>Hello, {{  }}</span> <!-- should suggest: "userName", "paymentMethods" -->
   </div>

• There is a set of magic function names you can use in doc comments to reference plugin-specific resolution tools:

  • As described in use table name instead of get_object_var(static) #123 you can use @param $row = Magic::dbRow('my_table_name') to tell IDE that $row is an associative array with keys matching columns in the my_table_name. For that to work, you need Data Source with your database credentials configured. Note, you can use any expression instead of 'my_table_name' string, like $this->tableName or static::getTableName()

If there are any questions concerning the format, you are welcome to file an issue - I'll answer there, and if it involves adding more formats, will reference your issue here.

[bravoman]

Very nice feature!

Does this also allow for specification of a ('virtual') @method phpdoc tag it's return value? If so, what would be the syntax for this?

[bravoman]

Also I'm curious... If I could add non-static PHP code like this, would that in turn also be type inferred?

Or would that just be asking for too much? 😉

[klesun]

Hi.
@method is currently not supported. I can add it, though, I guess it won't be hard.
I guess some Scala-ish syntax like that will look good:

/** 
 * @method array getData() = [
 *     'name' => 'John',
 *     'age' => 27,
 *     'children' => ['Tiffany', 'Bob', 'Marta'],
 * ]
 */

I'll write back when this is done (in few days maybe).

---

By non-static code you mean something like this?

$product = ['name' => 'insurance', 'quantity' => 3, 'price' => '80.00'];
/** @var $sale = ['sellingPrice' => '300.00', 'product' => $product] */
$sale = $this->sellProduct($product);

If so, there is no such feature yet either. Though I guess it could be added as well, if this is what you meant...

[klesun]

2019.02.28.001 - added support for @method doc return type.

@bravoman, please, confirm that I understood you correctly about the non-static php code before I start implementing it.

[bravoman]

Sweet! Yes, that is what I meant!

With regards to the non-static code I meant something like this:

/**
 * @method getById(int $id) = [
 *     'id' => 1,
 *     'username' => 'user_name'
 * ]
 * @method getAll() = [
 *     0 => self::getById(1)
 * ]
 */
class users_table {
}

Edit: it seems this already works if I use users_table::getById() instead of self::getById(1) 🙇 👍

😅

[bravoman]

I see this even works (assuming database is setup correctly in PHPStorm):

/**
 * @method getById(int $id) = (new \PDO('mysql:host=localhost;db=my_db_name;', 'random', 'random'))
 *                                ->query('SELECT * FROM domain_comments LIMIT 1')
 *                                ->fetch(\PDO::FETCH_ASSOC)
 * @method getAll() = [
 *     0 => users_table::getById()
 * ]
 */
class users_table {
}

You're my new hero ... 🏆 😉

[klesun]

Glad you liked it.
I'll make sure references like self::getById() and $this->someField will work as well in a while.