let's say I have the following
class Something extends ClassWithMagicMethods{}
Normally I would add a docblock for any properties I know exist even if accessed via a magic method
/**
* #property string $someVar
* #method SomeClass getSomeClass()
*/
class Something extends ClassWithMagicMethods{}
Which works great, but what I'm wondering is if we can have that docblock separate from the definition of the class. Two possible usecases:
Third party package that doesn't include the docblock but I want autocompletion from my IDE - I'd like to be able to just add my own docblock somewhere for it.
An extension system - In the file where the extension is defined I'd like to document the new properties this extension adds to the class.
I'm aware I could technically create a dummy ide_helper.php file that never actually gets run - just indexed by the IDE - unfortunately this causes any decent IDE to complain about duplicate declarations which I don't want as it also makes code navigation slower.
So - is it possible to document a PHP class by composing multiple docblocks external from the class definition?
Most of the results I've pulled up on SO are referencing just documenting unknown types where you use them which isn't what I need. I.E:
/** #var Something $something */
$something = FactoryMethodThing::create('Something');
See if this can help you :
phpdoc -d path/to/my/project -f path/to/an/additional/file -t path/to/my/output/folder
Source: http://docs.phpdoc.org/guides/running-phpdocumentor.html
Related
In my Laravel application I created a script that exports the attributes of my model classes to TypeScript interfaces. Thanks to those interfaces, my IDE knows which attributes the TypeScript objects should have.
Now, I'd like to go a step further and have my IDE also know about the attributes for each PHP class. For this, I'd like to create PHP Docstring definitions in separate files and link them to the actual class file. The linking would be okay to set manually.
My directory structure would look like this:
/classes/MyModel.php
/definitions/MyModel.php
The definition file for the class should only contain the Docstrings for the class:
// file: /definitions/MyModel.php
/**
* #var string $myStringAttribute
*/
Now, I'd like to include this generated file somehow in the class MyModel, so any IDE can know which attributes the Model can access from the DB. I already tried including the definitions file with include __DIR__ . '/../definitions/MyClass.php' but this did not work.
Outputting the Docstring definitions in the actual class file is not really an option for me. With separate files, I would just need to add a single line of code to the classes to link the definitions.
Is there a way of doing this that could work? Or maybe there are plugins for my IDE (PhpStorm/IntelliJ) which could do this (official Laravel Plugin did not do this)?
This is a quality-of-life question. I know I could write the docstrings for each class myself, but I prefer to have them generated automatically to be on par with the actual model definition in the database without manual work.
I created a PHP class in PhpStorm and allowed the IDE to auto-generate the DocBlock for the class. It included a package tag that exactly matched the namespace of the file as follows:
<?php
namespace frontend\controllers;
/**
* Class MethodController
* #package frontend\controllers
*/
class MethodController extends BaseRestController
{
}
I don't presently care to generate PHPDocumentor output, but I may want to at some point, so I would like to understand how #package is used. What surprises me is the message that PHP_CodeSniffer provided for this tag:
[phpcs] Package name "frontend\controllers" is not valid; consider "Frontendcontrollers" instead
Do I need to create some sort of table of contents to satisfy PHP_CodeSniffer?
Another perplexing twist is this quote from the PHPDoc website:
If, across the board, both logical and functional subdivisions are equal is it NOT RECOMMENDED to use the #package tag, to prevent maintenance overhead.
If I understand this correctly, there is no benefit in making the package exactly equal to the namespace. Why did PhpStorm provide this tag?
I've created new project using PhalconPHP 3.1.2. Everything works fine, but I have problem with IDE. In PhpStorm I've added ide/stubs/Phalcon from phalcon-devtools 3.1.2 as external libraries to dispose of warnings and errors.
But there is still one problem: in app/config/router.php (standard catalog structure created by devtools) I got line $router = $di->getRouter(); (also created by devtools) with warning: Method getRouter not found in Phalcon\Di\FactoryDefault.
There is no method in this class indeed: https://github.com/phalcon/phalcon-devtools/blob/3.1.x/ide/stubs/Phalcon/di/FactoryDefault.php -> https://github.com/phalcon/phalcon-devtools/blob/3.1.x/ide/stubs/Phalcon/Di.php
Now I don't have autocomplete of router's methods and this is problem for me. Did I do something wrong?
First of all -- I'm not familiar with Phalcon. These are my comments based on general PHP/PhpStorm experience.
So .. if you look at that PHPDoc in the last link you gave (stubs for Di.php) you will notice the code example there that has $request = $di->getRequest();.
If you just copy-paste that whole sample you will get the same "method not found" error ... as getRquest() is transformed at run time via magic __get() method.
The possible solution here is to create your own stub for your $di:
Create new class that will extend original Di, e.g.
class MyDi extends \Phalcon\Di
Add all those getRoute() / getRequest() etc methods there (could be real methods with empty bodies as in Phalcon's stub files .. or via #method PHPDoc tag)
Place such file anywhere in the project -- it will be used by IDE only.
When you are using your $di -- typehint it with your class, e.g.
/** #var \MyDi $di */
$di = new Di();
In the above code during runtime $di will be an instance of Di but for PhpStorm during development it will be MyDi so all type hints are in place.
As possible alternative -- instead of using magic via $di->getRoute() .. try $di->getShared('route') or similar.
If you use PhpStorm's Advanced Metadata functionality it will allow to get correct type based on parameter value.
$di->getRouter() is magic method, Phalcon\Di implements __call method and it gets router service this way if you use getRouter().
If you want you can use PHPStorm metadata and use $di->get() https://www.google.pl/search?client=opera&q=phpstorm+metadata&sourceid=opera&ie=UTF-8&oe=UTF-8
Hello i have a bootloader where i define some basis services like
/** #var $serviceManager Zend\ServiceManager\ServiceManager */
$serviceManager = new ServiceManagerComposite(new ConfigurationComposite($configuration['service_manager']));
But this type of documentation is not available trough my legacy code for hinting, as i found out this will define the variable only on tht one php file. But because i use it as a legacy acess point for my code i need it for the whole php project...
Any sugestions what type of documentation would work with the IDE hinting from Netbeans?
You'd probably need to duplicate at least the first use of $serviceManager with the same #var docblock in each file. If NetBeans is not already resolving scope for you via requires and includes, then this would be the only way to put a context on that "local" variable in the file you're in.
Sangoku is perfectly right!
/* #var $serviceManager Zend\ServiceManager\ServiceManager */
Should do the trick
I am making usage of
/* #var $var Type */
really often for NetBeans can then autocomplete methods and stuff in code.
Still I think its a very useful feature but sometimes I got objects of
classes extending one more class and implementing multiple interfaces.
Or I even got a transitive class hierarchy.
I don't know a way to tell NetBeans that it shall be using autocomplete for
all these interfaces and upper-layer parent classes.
I would like to do so for of course every of these interfaces / classes got
dedicated methods (which are defined somewhere in case of interfaces...)
I tried something like this:
/* #var $var TypeA|\TypeB|\TypeC */
because I saw NetBeans will generate a similar documentation for methods returning
different class objects due a switch/case. But this seems to work only for the
#return notation.
I also tried
/* #var $var TypeA|TypeB */
Also not working...
NetBeans will autocomplete the last told Type in this case but not a combination of both/all told classes.
How can I document so my autocomplete works as desired (a summary of methods of all classes /interfaces I listed)?
regards!
If I understand you correctly, you are asking to chain hint through your PHP code.
The problem is netbeans has no way of knowing what an object actually is; unless you tell it. The solution is to use the #property command in your object decleration to forward type define the objects members , be it a class or interface.
/**
#property classMyClass1 $clsMyClass1
#property classMyClass2 $clsMyClass2
*/
class baseClass{
public $clsMyclass1;
public $clsMyClass2;
public function __construct() {
$this->clsMyClass1 = new classMyClass1();
$this->clsMyClass2 = new classMyClass2();
}
}
$foo = new baseClass();
Now when you type your code in netbeans it will know what hinting to display on your last typed object
$foo->clsMyClass1->
So long as each class has a forward property decleration you can chain as long as you want
$foo->class1->class2->class3->...
The above code would need the autoload() function to load the correct class files....
Hope this helps you!