When in a class there is the ability to autocomplete certain methods, e.g. the constructor or some inherited functions. I'd like to add some custom methods like public function foo():void to the autocomplete if a specific trait is applied. First I thought of Live Templates but they cannot be constrained to be only applied if there is a certain trait present.
Do you have any idea how I could achieve this? Maybe by generating some docblocks?
You can use #method tag in PHPDoc comment for the trait to declare such "virtual" methods. Modern PhpStorm versions can offer such signature when invoking code completion when declaring a new method.
<?php
declare(strict_types=1);
/**
* #method void traitPublic()
*/
trait T
{
private function traitPrivate(): void
{
}
}
class C
{
use T;
}
Related
I am looking to extend a trait by using it in another trait. However the trait is using a method that looks like it isn't extending. The trait works, so I am wondering how.
Why does this trait have access to the markEntityForCleanup method?
The code is in this repo for Drupal Test Traits
<?php
namespace weitzman\DrupalTestTraits\Entity;
use Drupal\Tests\node\Traits\NodeCreationTrait as CoreNodeCreationTrait;
/**
* Wraps the node creation trait to track entities for deletion.
*/
trait NodeCreationTrait
{
use CoreNodeCreationTrait {
createNode as coreCreateNode;
}
/**
* Creates a node and marks it for automatic cleanup.
*
* #param array $settings
* #return \Drupal\node\NodeInterface
*/
protected function createNode(array $settings = [])
{
$entity = $this->coreCreateNode($settings);
$this->markEntityForCleanup($entity);
return $entity;
}
}
I found the issue.
When using the Drupal Test Traits package you are expected to use your own custom php-unit bootstrap.php and manually load the required packages.
Adding this line to the bottom of the bootstrap script will gain access to the namespace in php.
// <?php is needed for SO to do the syntax highlighting.
<?php
// Register more namespaces, as needed.
$class_loader->addPsr4('weitzman\DrupalTestTraits\Entity\\', "$root/vendor/weitzman\drupal-test-triats\src\Entity");
I need to add $variable in my php return document
for example I have this function :
/**
* #return \Panel\Model\{$Service}
*/
public function getService($Service){
// I call service `foo` from Model folder
}
I see this post : What's the meaning of #var in php comments but it has no information about how to do it , and also study #var-phpdoc but that has nothing for me.
if you ask me why I should do that , because I want use phpStorm Ctrl+Click advantage on $this->getService('foo')->bar()
thanks in advance
As LazyOne said in the comments already PHP interfaces should solve your problem. You can 't use variables in PHPDoc formatted comments. Sure, if you use an IDE like PHPStorm with a plugin that enables the usage of variables in PHPDoc comments, the problem is solved for yourself. What, when other developers, which don 't use PHPStorm or the relevant plugin, want to work in the same project? In my view you should use php native functionality to solve your issue.
Here 's a short example how to use interfaces.
declare('strict_types=1');
namespace Application\Model;
interface ModelInterface
{
public function getFoo() : string;
public function setFoo() : ModelInterface;
}
The only thing you have to do now is using this interface with your models like in the following example.
declare('strict_types=1');
namespace Application\Model;
class FooModel implements ModelInterface
{
protected $foo = '';
public function getFoo() : string
{
return $this->foo;
}
public function setFoo(string $foo) : ModelInterface
{
$this->foo = $foo;
return $this;
}
}
As you can see the FooModel class implements the ModelInterface interface. So you have to use the methods declared in the interface in you model class. This means, that your getService Method could look like the following example.
/**
* Some getter function to get a model
* #return \Application\Model\ModelInterface
*/
public function getService($service) : ModelInterface
{
return $service->get(\Application\Model\Foo::class);
}
Your IDE knows now which methods the returned class can use. It allows you to use chaining and some more features. While typing your IDE should know now, that the returned class can use getFoo and setFoo methods. Further the setFoo methods enables comfortable chaining for calls like ..
// variable contains the string 'foo'
// your ide knows all methods
$fooString = $this->getService($serviceLocator)->setFoo('foo')->getFoo();
Are you using Symfony? Then you could use the Symfony plugin that solves this problem for you. For other frameworks, there should be similar solutions. If you use your own framework, you need to write such a plugin on your own, as PhpStorm can not resolve the given class otherwise.
I think what you are looking for is phpdoc.
https://docs.phpdoc.org/guides/docblocks.html
/**
* #param string $Service This is the description.
* #return \Panel\Model\{$Service}
*/
public function getService($Service){
// I call service `foo` from Model folder
}
Let's say I've
an abstract class with with one abstract method.
2 child classes that define that abstract method in their own way.
A factory that returns an instance of one of 2 child classes based on arguments.
Following is the sample code
abstract class Datalist{
abstract public function render($arg1, $arg2);
}
class Datalist_Table{
public function render($arg1, $arg2){
/* do something here */
}
}
class Datalist_List{
public function render($arg1, $arg2){
/* do something here */
}
}
class DatalistFactory{
/**
* usual stuff
*
* #return Datalist
*/
public static function build($args){
$class_name = 'Datalist_' . $args['type'];
return new $class_name($args['m'][0], $args['m'][1]);
}
}
//in some other file
$list = DatalistFactory::build($args);
$list-> ....
My problem
My IDE (PHPStorm) does not hint on the $list->render(). My guess is that because it has been declared as an abstract.
Question
What should I put in front of #return in PHPDoc for DatalistFactory::build() so that the IDE hints on the functions defined in child classes as well.
P.S.
I've tried instructions in following questions with no success
phpDoc notation to specify return type identical to parameter type
PHPDoc: Is is possible to reference the object property descriptions from factory method docblock?
PHPDoc preconditions
PHPDoc for fluent interface in subclass?
You need to open this file in project. I use phpstorm 8.0.3 create new file in project and insert your code. All works fine =)
I am using a framework that allows adding new components to the framework's base class. Is there any way to document these new methods without changing the frameworks files so I can click through to the method in my IDE.
I highly recommend against trying to inject a subclass. If the framework instantiates the class you're extending directly, you'll need to find a way to get it to use your subclass instead.
NetBeans and PhpStorm (and probably many others) will combine elements from multiple definitions of the same class/interface. This allows you to add properties and methods to any existing class without modifying the original source.
/**
* Framework controller base class.
* Provides helpers via __call().
*/
class Framework_Controller { ... }
Now create a file in your code base that you never require containing the same class definition. Your IDE should still parse it and merge its elements with the class above:
if (false) { // Safety first!
/**
* ACME Co. controller base class.
*
* #method ACME_Model_User getUser Load user via authentication helper
*/
class Framework_Controller { /* nothing to add */ }
}
You can try using an interface and declaring the methods normally instead of with #method. That is what we did with Zend_View since it's already an interface. I haven't tried mixing class with interface to see if PhpStorm likes it.
It depends mainly on IDE you are using. I think you should extend base class and add there some new methods/properties with phpdoc comments. Of course changing framework's files is no solution as you already mentioned
You could extend the original class, redefine the function, with new doc, and call the parent function.
e.g.
class newClass extends originalClass
{
/**
* New PHPDoc
*/
function functionName($a)
{
return parent::functionName($a);
}
}
Try to use #see or inline #link directives.
I have a trait that must always be mixed in to a subclass of \PHPUnit_Framework_TestCase. PhpStorm doesn't know this. Is there anything I can do to get PhpStorm to autocomplete and "typecheck" things like assertNull inside the trait?
<?php
trait MyTestUtils
{
public function foo()
{
$this->assertNu // autocomplete?
}
}
The best I could come up with so far is putting the following in each method:
/** #var \PHPUnit_Framework_TestCase|MyTestUtils $this */
But this is repetitive and doesn't understand protected memebers. Is there a better option?
Besides using the php docblock to document $this, the only other way I'm aware of, which also, arguably makes your trait more "safe" anyway, is to define abstract methods on the trait itself, e.g.:
trait F {
/**
* #return string[]
*/
abstract public function Foo();
/**
* #return self
*/
abstract public function Bar();
}
abstract class Bar {
use F;
/**
* #return bool|string[]
*/
public function Baz () {
if ($this->Bar()) {
return $this->Foo();
}
return false;
}
}
UPDATE: Since PhpStorm 2016.1.2 (build 145.1616) autocompletion in traits works out-of-the-box. It is smart enough to figure out what classes use the trait, and then provide the autocompletion. Link to the issue: https://youtrack.jetbrains.com/issue/WI-16368
Previously replied with:
You can use:
#method \PHPUnit_Framework_TestCase assertTrue($condition, $message = '')
...in docblock of the trait itself, but the downside is that you'd need to put #method for each method that you'd like to have autocomplete for, which is not too bad if you're using a sane number of method calls in your trait. Or, "document" only those methods that you're using most often.
I would argue that this is not a valid use-case for a PHP trait. Your trait, as written is not guaranteed to only be used on classes that extend \PHPUnit_Framework_TestCase. This introduces very tightly coupled code. The best practice of Traits is for them to be very loosely coupled and only be aware of their own contents.
I would instead recommend that you either:
create a subclass of \PHPUnit_Framework_TestCase that your test cases that need this functionality can extend
create custom assertion classes. These can many times be used for doing groups of custom assertions.
Both techniques are detailed here: http://phpunit.de/manual/4.1/en/extending-phpunit.html
These are the two recommended best practices for where to place helper methods such as these.