I'm having a hard time finding out a nice clean way to generate docs. PHPdoc still seems a little scattered.
In any case, I can't seem to get it to generate source code with highlighting, which I seem to have a compulsive need for - being a stack overflow user :D
Here's the command I'm running:
phpdoc project:run --directory /var/www/symbiostock/wp-content/themes/symbiostock/ --target /var/www/PhpDocumentor-output/ --template responsive --sourcecode --force
Without the --force parameter, it tells me I have too many arguments. With it, it just rolls through everything without any apparent generating of highlighted source code.
Is this template sensitive? Only some templates do source inclusion?
I find documentation on phpdocumentor slightly deficient in a few areas (ironically) so I thought I might just post the question.
I don't think that 2.x has implemented the --sourcecode option yet. It's available in 1.x, but 1.x does not handle new features added in PHP 5.3 and beyond.
Related
Our time is getting bigger and bigger, and we we need to have consistent code formatting in our repos. Some devs are using VS Code, some are using PhpStorm.
Now there is already a popular extension https://prettier.io/docs/en/configuration.html and it works on most popular IDEs out there. The problem we are facing it, it still doesn't format Blade files from Laravel. Is there a way we can tell Prettier to do that? Will it work for both VS Code and PhpStorm, and other IDEs?
What do other people do to over come this problem? Multiple devs using different IDEs and still same formatting rules somehow so that git is not noisy and overwhelming?
UPDATE:
I found a npm package called blade-formater which I installed using npm install -g blade-formatter this command and I can run something like blade-formatter -w "resources/views/**/*.blade.php" to format all blade views.
Now to make it work across IDEs, I am thinking I can somehow call it when blade files are changed, and a watcher detects it and calls this command. I have Laravel Mix, so I think it should be possible but I am not sure how. Can anyone point me in the right direction?
When I generate my ctags file, it seems to be parsing content inside comments too. For instance, using Vim's plugin Tagbar, I can see in the list of functions non-existent functions such as:
is
in
just
What is happening here is that ctags is going into comments and finding things like:
"This function is...", thinking that "is" is a function, it is then adding an entry for it in the tags file.
I am wondering if there is an easy way to tell ctags not to parse contents inside comments.
I have found that apparently there was a fix for this to be released after 5.8.0 but I am not sure whether this has already been released or not, my ctags version is 5.8.0.
This is related to a PHP project but I guess it would be nice if the answer can cover a solution that would work for any programming language (if such a thing is possible).
Example:
The following comment to a function generates the tag "is" and lists it as a function:
/**
* This function is run to set certain preferences
*/
There's a bug in ctags 5.8. Fortunately, one day after it was released, jafl committed revision 729 to fix the problem. Unfortunately, there has not been a release since then.
Fortunately, the project has been forked as "Universal Ctags." Here's how to install that from source.
# Get rid of 5.8.
sudo apt-get remove exuberant-ctags
# autoconf is needed to assemble the configure files
sudo apt-get install autoconf autoconf-doc
git clone https://github.com/universal-ctags/ctags.git universal-ctags
cd universal-ctags
./autogen.sh
./configure
make
sudo make install
Exuberant Ctags has a large variety of languages already built into it. Each of these has a custom parser tailored to that language. Of course, it doesn't make sense to include comments / commented-out sections of code in the tags file. If that happens, it is a bug in the language's parser and must be fixed in the ctags code.
Note that Exuberant Ctags also supports extension to new languages via regular expressions. With these, it can be very difficult / slow / impossible to exclude comments (as there may be a large preceding context to consider, and the language syntax may not be fully representable as regexp), and you would have to live with this, or apply workarounds like preprocessing the comments out of the sources before processing them.
Problem
I have a legacy codebase I need to analyze and determine dependencies. Particularly the dependencies on classes (internal/external) and extensions (Memcache, PDO, etc).
What I've Tried
I have reviewed the tools listed in Is there a static code analyzer for PHP files?. Unfortunately, this post is dated and most of the promising tools like phpCallGraph no longer work.
My thought was to analyze the code lexically and look for class tokens. Reviewing a list of these would at least allow me to visually determine dependencies. However finding OtherClass in the following code may be complex:
$classname = 'OtherClass';
echo $classname::doubleColon();
In the end, I doubt I'm the first to need this. I'm sure a tool or combination of tools exist to provide what I need. So I'm asking the SO community before writing this myself.
Update
Ideally this tool will analyze multiple files with complete code coverage. As such, tools like Xdebug, while great, are not solutions to this exact problem.
Instead of phpCallGraph you could use Gopal Vijayaraghavan's inclued extension which in combination with Graphviz gives you a nice looking graph of all included files for a certain execution path.
Example:
Moreover, I'd recommend Xdebug (a PHP debugger) which offers a profiler that outputs data consumable by Valgrind. Use the debugger with a compatible IDE to follow the execution path (which helped me a lot to wade thru e.g. Drupal's massive call-stack).
Combine both and you should get a fairly thourough overview.
EDIT
Searched the web and found nWire for PHP - an eclipse plugin that looks like it could be the right tool for you (30 day free trial which should be enough to give you a head start).
I think PhpCodeAnalyzer is exactly what you're looking for - https://github.com/wapmorgan/PhpCodeAnalyzer
It print list of all used external extensions in code base.
Has anyone got these to work together seemlessly? I have tried, had some success using the plugin at http://phing.info/trac/wiki/Users/Documentation/CruiseControl, but have failed to:
Get the metrics graphs working (nothing appears)
Enable the "PMD" - project mess detection - reports
Are there any other ant-specific commands that must (can) be run in addition to my phing build script?
Also, the front page of the reports section dumps a heap of log information, and I'm trying to get rid of that too.
Cheers for any help ... we are running phing 2.3.0 and phpUnderControl 0.4.7.
Paul
Our application framework makes heavy use of Phing, and we've got that integrated under CI with phpUnderControl. We do have the metrics and PMD working now, and honestly, it was a little bit of an accident that it started working. But we're still missing the code coverage (working on it) and the phpDoc output (working on that too). I'll try to remember to come back and update this when we're done.
I have found that the main reason for the metrics not showing up is an incompatibility with the ez library that phpuc uses for the rendering. You'll get this NullPointerException on the page, right? Then when you try to run a build manually, you'll get this obscure error about index and divide by 0? What's happening is the ez graphics library that ships with phpuc is old, and you have to upgrade it. I hope that's a clue for you. We didn't have trouble with PMD stuff, so I don't know why that wouldn't work for you. If you want to update your question with more specifics, maybe I can elaborate on what's worked for us?
To answer my question, in the end I figured it was easier to just use an ant build script to make everything work.
I think phing is good when starting out, and has an excellent dbdeploy feature (which I use in phpUC), but for getting the metrics and the PHPMD integrated you are better off using ant - the XML is not hard.
Cheers
I'm going to be doing some PHP editing for my job this summer, and am looking for an effective Emacs setup for editing it. I'm already heavily invested in Emacs, so switching to another editor is not worthwhile.
Right now, I have nXhtml-mode, which provides a PHP mode with syntax highlighting (there are at least three different ones in the wild) as well as MuMaMo for editing PHP embedded in HTML. I just started using Auto-Complete and Anything for programming and general Emacs stuff, respectively.
What I'm really looking for is an effective way to get Emacs to really understand the project, beyond just highlighting. Etags looks like a good option, but it looks like the process for generating new tags is kind of arduous and manual (or at least not invisible). The nice thing about Etags is that they integrate well with Anything and Auto-Complete. Other potential options are gtags (though I'm hesitant to install non-elisp files, just for the complexity), vtags, or Semantic, which I've messed with before and seems complicated to set up, plus it doesn't look like it has support for PHP.
Another option is Imenu, but it only works for the current buffer, and I would like to be able to jump to function definitions in other files (preferably using Anything for completion of the name).
The projects I will be working on are not that big (about 30,000 lines total), so the overhead of Etags probably won't be that big of an issue, but I'd rather not use it if there is a better solution.
So what is your preferred PHP editing system?
In addition to features you are already familiar with, I suggest you the followings.
ETags
I do not use ETags, but there is a question already on SO How to programmatically create/update a TAGS file with emacs. No good answer was posted, though, but it may be a good entry point to get an idea.
Debugging
Flymake is a mode to get on the fly syntax checking. It has support for PHP as well. It hints at syntax errors immediately as you type. The Flymake version shipped with Emacs 23 contains PHP support. If you have previous version, check Sacha Chua's post on Emacs and PHP: On-the-fly syntax checking with Flymake.
Another useful package is Geben that allows you to debug your scripts interactively. For PHP, you can use XDebug. There is a detailed tutorial on how to do that, see Debug php in emacs with geben.
Documentation lookup
PHP Mode has a nice feature to lookup the function's definition in PHP's manual in your web browser (M-x php-search-documentation or C-c C-f). You can combine it with Emacs-W3M to get the relevant manual page without leaving Emacs.
web-model.el (available on web-mode.org) handles pretty well php blocks embedded in an html document. This major mode will also highlight js and css parts.
As an alternative to ETags, consider GNU Global, aka "GTags". Global is a lot smarter about finding tags tables, and is fairly fast to update. Emacs-fu has a nice post about doing this on-the-fly.
BTW, if you're using the Windows port of GNU Global with a Windows Emacs build, use the DJGPP ("DOS") version. The MinGW ("Win32") build seems to have a problem with path names.
In addition to the answer given on May 28 '09, I think I can add some packages to it which enhanced my PHP experience on Emacs.
Auto-completion
ac-php is in my opinion a good additions to Etags. All references to a tag will be found with etags, but the definition with ac-php. ac-php is also configurable to which directories should be included. For example, while developing a wordpress plugin, you can add a reference to the directory containing the wordpress files in .ac-php-conf.json (which resides in the project root) and it will auto-complete, jump to reference, etc. This package supports company-mode and auto-complete.
Here's an example configuration of ac-php:
(use-package ac-php
:ensure t
:bind (:map
php-mode-map
("M-+" . ac-php-find-symbol-at-point)
("M-]" . ac-php-location-stack-back)
("<menu> r" . ac-php-remake-tags)
("<menu> R" . ac-php-remake-tags-all)))
Another option would be to use phpactor, but the Emacs interface is at the time of writing still in alpha stage, with which I also hardly have any experience - except for the constructor completion, which works pretty well.
Error checking
In addition to syntax errors, Flycheck supports phpMessDetector and phpCodeSniffer out of the box. This enables you to have more enhanced notice/warning/error reporting based on supported coding standard and best practices.
Another package I like for static analysis is PHPStan Emacs interface, which reports potential errors in your code (including incorrect type hints).
Additional formatting
I also use phpcbf (which apparantly is archived). This package formats the buffer into the wanted coding standard.
Semantic
For anyone in the dark, Semantic is a built-in Emacs package and provides IDE like features. Here's an example how to include semantic for php-mode:
(add-hook 'php-mode-hook (lambda ()
(require 'semantic/symref/grep)
(add-to-list 'semantic-symref-filepattern-alist '(php-mode "*.php" "*.inc"))
(semantic-mode)))
Imenu
For including imenu jumping to definitions, another example configuration:
This is the sidebar for jumping to in-file methods and functions.
(use-package imenu-list
:ensure t
:config
(setq imenu-list-focus-after-activation t)
:bind (:map php-map
("<menu> \\" . imenu-list-smart-toggle)))
Example config for helm support in jumping to definitions in all project files:
(use-package imenu-anywhere
:ensure t
:after helm
:bind (:map php-map
("<menu> |" . helm-imenu-anywhere)))
Additional debugging
Besides geben, I like to use psysh, which by dropping in eval(\Psy\sh()); gives a repl on that line of code and gives access to all definitions and whatever else one would have access to (ofcourse, after requiring it in composer).
More generally handy packages
Snippets
Maybe a bit obvious for everyone already experienced with Emacs, but yasnippet is also very handy for writing your own templates. There are also packages that include a lot of predefined templates for all sorts of languages, but I write my own to keep Emacs a little less bloated than my set-up already is, it also helps me remember them more easily.
Project management
Excuse the obviousness again, but Projectile is also a very good package which by default includes git support for scoping the project.
Offline documentation
If you use Zeal for offline documentation browsing, there's also zeal-at-point. Example configuration, if you use, lets say: PHP, CodeIgniter and WordPress:
(use-package zeal-at-point
:ensure t
:bind (("<menu> z" . zeal-at-point))
:config
(add-to-list 'zeal-at-point-mode-alist '(php-mode . ("codeigniter" "wordpress" "php"))))