PHP has a function called get_meta_tags which can read meta tags of HTML files. However, as far as I know there is no standard way to define meta tags for PHP files. The de facto solution seems to be to add comment to the top of the file like so:
<?php
# Author: Ood
# Description: Hello World
?>
Is there any way to read these "meta tags" with PHP similar to the way get_meta_tags works using the default PHP library? Preferably without parsing the entire file with file_get_contents followed by a regex for best performance. If not, maybe someone knows of a better solution to add meta data capabilities to PHP files. Thanks in advance!
In our project we are happy with the standard JavaDoc that was adopted by PHPDoc using the #field syntax as you might know it from any PHP function or class definition. This is pretty fine readable using the PHPDocumenter.
In our adoption we use the very first multi-line comment, ie anyting between /** and closing tag */, using the JavaDoc style to describe all the details about the current script.
So to adopt your example in our project we would have following syntax:
<?php
/**
* #author Ood
* #desc Hello World
*/
Of course you may end up with your custom function reading the beginning of the php file parsing just the very first multi-line comment to get the script description aka meta tags.
How to write code blocks using phpDocumentor while writing tutorials/extended documentation?
I have tried <programlisting>, it can generate the <code> tag , but it does not parse its contents.
<refentry id="{#id}">
<refnamediv>
<refname>Guide for MyApp</refname>
<refpurpose>To demonstrate ...</refpurpose>
</refnamediv>
<refsynopsisdiv>
<author>
My Name
<authorblurb>
{#link mail#mail.com My Name}
</authorblurb>
</author>
</refsynopsisdiv>
{#toc}
<refsect1 id="{#id intro}">
<title>User Guide for MyApp</title>
<para>
Some Description
</para>
<programlisting>
$some = 'code';
</programlisting>
</refsect1>
</refentry>
This is actually very easy once you know how. You just need to set the role attribute on the programlisting element.
<programlisting role="php">
$some = 'code';
</programlisting>
I couldn't find this documented anywhere, other than a brief mention in the release notes, but from looking at the code, there seem to be four roles that are supported:
php - adds PHP syntax highlighting to the content and includes a line number on every line.
tutorial - adds HTML syntax hightlighting to the content and includes a line number on every line.
xml - adds pre tags around the content, but otherwise no syntax hightlighting and no line numbers.
html - treats the content as raw HTML, so you can use whatever markup you like.
Any time you want to use angle brackets, though, you will need to escape those characters or wrap the content in a CDATA section. This even applies when you want to use raw HTML. If not, the parser will try and interpret the content as XML.
For example, a raw HTML sample would look something like this:
<programlisting role="html">
<![CDATA[
<b>This sentence will be bold.</b>
]]>
</programlisting>
Also note that all of this applies to the initial version of phpDocumentor. The new version (phpDocumentor 2) doesn't appear to support tutorials/extended documentation as far as I can tell.
I checked it and I think you can use javascriptMVC documentation tool. I thik Documentation Tool.
and a demo of it is here. and I suggest you to try this.(-:
here is an output of documentJs of javascriptMVC which is /i think the thing you want. or at least I hope.(-:
and about phpDocumentor As I said I need some explains to get what you mean but for now please check these. link1.
link2 . (if the following is the thing you want).
/** #type int This is a counter. */
$int = 0;
// there should be no docblock here
$int++;
Or:
/**
* This class acts as an example on where to position a DocBlock.
*/
class Foo
{
/** #type string|null Should contain a description if available */
protected $description = null;
/**
* This method sets a description.
*
* #param string $description A text with a maximum of 80 characters.
*
* #return void
*/
public function setDescription($description)
{
// there should be no docblock here
$this->description = $description;
}
}
Another example is to document the variable in a foreach explicitly; many IDEs use this information to help you with auto-completion:
/** #type \Sqlite3 $sqlite */
foreach($connections as $sqlite) {
// there should be no docblock here
$sqlite->open('/my/database/path');
<...>
}
You can user zend studio tool which can generate selected project documentation automatically
I want to automatically generate block comments for documentation using vim.
Something like:
/**
* comment
*/
are there any plugins for this?
Vim has this functionality built-in. See :help format-comments for details. Basically if you have filetype plugin on in your ~/.vimrc and are using a bracket language (like C, C++, Java, javascript, etc.), you can type /**<cr> and it will expand to:
/**
* _
where _ is the cursor position. When you're done with the comment block just hit / to end it.
A low-budget way of simplifying a Vimmer's life with C- or Java-style block comments is to add the following mapping to .vimrc.
autocmd FileType c,java inoreabbrev <buffer> /** /**<CR>/<Up>
That way, whenever you type /**<Enter> in your C or Java source it will be expanded to the following, with the cursor at _:
/**
* _
*/
Edit: As #Conner mentioned, you need to have filetype plugin indent on in your vimrc to make this work.
I have never, ever, seen a PHP file using hashes (#) for commenting. But today I realized that I actually can! I'm assuming there's a reason why everybody uses // instead though, so here I am.
Is there any reason, aside from personal preference, to use // rather than # for comments?
2021 UPDATE: As of PHP 8, the two characters are not the same. The sequence #[ is used for Attributes.(Thanks to i336 for the comment)
Original Answer:
The answer to the question Is there any difference between using "#" and "//" for single-line comments in PHP? is no.
There is no difference. By looking at the parsing part of PHP source code, both "#" and "//" are handled by the same code and therefore have the exact same behavior.
PHP's documentation describes the different possibilities of comments. See http://www.php.net/manual/en/language.basic-syntax.comments.php
But it does not say anything about differences between "//" and "#". So there should not be a technical difference. PHP uses C syntax, so I think that is the reason why most of the programmers are using the C-style comments '//'.
<?php
echo 'This is a test'; // This is a one-line C++ style comment
/* This is a multi-line comment.
Yet another line of comment. */
echo 'This is yet another test.';
echo 'One Final Test'; # This is a one-line shell-style comment
?>
RTM
Is there any reason, aside from personal preference, to use // rather than # for comments?
I think it is just a personal preference only. There is no difference between // and #. I personally use # for one-line comment, // for commenting out code and /** */ for block comment.
<?php
# This is a one-line comment
echo 'This is a test';
// echo 'This is yet another test'; // commenting code
/**
* This is a block comment
* with multi-lines
*/
echo 'One final test';
?>
One might think that the # form of commenting is primarily intended to make a shell script using the familiar "shebang" (#!) notation. In the following script, PHP should ignore the first line because it is also a comment. Example:
#!/usr/bin/php
<?php
echo "Hello PHP\n";
If you store it in an executable file you can then run it from a terminal like this
./hello
The output is
Hello PHP
However, this reasoning is incorrect, as the following counterexample shows:
#!/usr/bin/php
#A
<?php
#B
echo "Hello PHP\n";
The first line (the shebang line) is specially ignored by the interpreter. The comment line before the PHP tag is echoed to standard output because it is not inside a PHP tag. The comment after the opening PHP tag is interpreted as PHP code but it is ignored because it is a comment.
The output of the revised version is
#A
Hello PHP
If you establish some rule sets in your team / project... the 2 types of comments can be used to outline the purpose of the commented code.
For example I like to use # to mute / disable config settings, sub functions and in general a piece of code that is useful or important, but is just currently disabled.
There's no official PSR for that.
However, in all PSR example code, they use // for inline comments.
There's an PSR-2 extension proposal that aims to standardize it, but it's not official: https://github.com/php-fig-rectified/fig-rectified-standards/blob/master/PSR-2-R-coding-style-guide-additions.md#commenting-code
// is more commonly used in the PHP culture, but it's fine to use # too. I personally like it, for being shorter and saving bytes. It's personal taste and biased, there's no right answer for it, until, of course, it becomes a standard, which is something we should try to follow as much as possible.
Yes, however there are cross platform differences.
I use # all the time for commenting in PHP, but I have noticed an adoption difference.
On windows keyboard the # key is easy to use.
On mac keyboard # key mostly isn't present.
So for mac users, [Alt] + [3] or [⌥] + [3] is more difficult to type than //, so // has become a cross platform way of displaying code with comments.
This is my observation.
From https://php.net/manual/en/migration53.deprecated.php
"Deprecated features in PHP 5.3.x ...Comments starting with '#' are now deprecated in .INI files."
There you have it. Hash '#' appears to remain as a comment option by default by not being deprecated. I plan to use it to distinguish various layers of nested if/else statements and mark their closing brackets, or use to distinguish code comments from commented out code as others have suggested in related posts. (Note: Link was valid/working as of 4/23/19, although who knows if it'll still be working when you're reading this.)
Is there any reason, aside from personal preference, to use // rather
than # for comments?
I came here for the answer myself, and its good to know there is NO code difference.
However, preference-wise one could argue that you'd prefer the 'shell->perl->php' comment consistency vs the 'c->php' way.
Since I did approach php as a poor man's webby perl, I was using #.. and then I saw someone else's code and came straight to SO. ;)
OP Question: "Is there any reason, aside from personal preference, to use // rather than # for comments?"
One 2021 Answer, which is certainly not the only answer as we see in this thread:
If you're using Visual Studio Code and using regions to block your code, then you must use # rather than // to define the region. To the question, No, even for this use case : If you are commenting out a region, you can use # or // or /** */, the technique you use for this is personal preference.
Examples for block definition in VSCode :
#region this is a major block
/** DocBlock */
function one() {}
/** DocBlock */
function two() {
#region nested region based on indentation
// comments and code in here
# another nested region based on indentation
// foo
#endregion
#endregion
}
#endregion
On Fold of the inner block:
#region this is a major block
/** DocBlock */
function one() {}
/** DocBlock */
function two() {
> #region nested region based on indentation
}
#endregion
On Fold of the outer block:
> #region this is a major block
I cite the following specific usage which one might be tempted to try, but these do not work. In fact this is exactly how you DISable a #region block:
// #region
// #endregion
/** #region */
/** #endregion */
As to commenting out a region in VSCode:
/** You can now collapse this block
#region Test1
// foo
#endregion
// everything through to here is collapsed
*/
// #region Test1
// folding is disabled here
// #endregion
# #region Test1
// this also disables the fold
# #endregion
All of that said, "Is there any reason, aside from personal preference, to use // rather than # for comments?" I agree with comments in this thread and in the other thread: // is more commonly recognized and used, which is usually a good reason to use that comment style over #.
Final note, be careful about nesting based on indentation, as code formatting can remove your manual indentation and thus ruin your scheme of nested blocks based on comments. I've tested this with both # and // (which BTW, // nests on indentation too. Again, in context with the OP question, No, there is no reason to use // over # for nested indentation in this context in the current VSCode because both work exactly the same. However, this is a use case for using # over //.
Ref - no extension required, verified in 1.62.3. See notes on indentation there as well.
Comments with "#" are deprecated with PHP 5.3. So always use // or /.../
I am about writing own simple syntax highlighter in PHP. I've done basic algorithm based on regular expressions and string replacement, but what I really don't know is way how to disable replacing keywords which are commented.
For example:
/**
* Some class
*
* #property-read $foo
*/
class Test
{
private $foo;
public function __construct()
{
}
}
Now my solution simply highlight defined keywords (like class or variables) but also those which are commented.
Any solution for this problem?
Why not use PHP's tokenizer to do the job for you? That way, your syntax highlighter will parse the PHP code the exact same way the Zend Engine does, which is probably going to give you a lot better results than a regular expression.
Why not borrow lessons from how vi or vim already does this? long back I remember for some custom tag based language we developed, we wanted syntax highlighting in VI and VIM , that is when we changed few .vi sort of configuration files where we mentioned, all the meta data like which color to what kind of tag, what are tags possible etc.
Looking more into how vi or vim or any text editor does this might be more helpful!
You could exclude the commented lines by this logic:
if line starts with /** disable highlight
if next line starts with * do nothing and check next line
if line starts with */ reenable highlight
Just a quick guess and can be defined more precise, but should work as a logic.