7 replies to this topic

[TenLeftFingers]

The technical description for the PHP function htmlspecialchars() is:

string htmlspecialchars ( string $string [, int $flags = ENT_COMPAT | ENT_HTML401 [, string $charset [, bool $double_encode = true ]]] )

I can see that the return type is 'string' and that the function can take up to four arguments. I know that the values in caps are constants and that the last argument has a default value if not supplied.
My questions are;
How do I read this? The last three arguments are nested in square brackets - does this mean that they depend on each other in order from left to right?
Is the $flags arguements limited to only the two shown after the equals sign? (what does the '|' tell me?)
Since the last argument has a default value, is that adopted internally by the function even if the other variables ($flags, $charset and $double_encode) are not given?.

And finally, the above text isn't a function definition - so is it an API? Is there a name for what it is / says?

Many thanks,
Ten

[WingedPanther]

htmlspecialchars returns a string. It has a string as a mandatory argument. There is an optional argument that is an int called flags. If that is passed, you can also optionally specify the character set with a string. If that is passed, you can optionally also specify whether to double_encode it. Double encoding defaults to true, flags defaults to ENT_COMPAT | ENT_HTML401.

[Alexander]

It is purely a documentary of the function, it was likely added as a comment above the real code definition and automatically generated as a single string for php.net

In C you would usually define a return type before a function name, i.e. "char[] func()", and as PHP borrows/is written in C it simply has "string foo(...)" or "int foo(...)" to show what it may return.

You would read from left to right, "|" means "or", for example only one or the other parameter may be chosen. Anything in [] is optional as well, as you'd likely not need to use the character set often and would not like to have to type it in every time.

[TenLeftFingers]

Thank you WingedPanther & Alexander. I understand most of it now. I'm still not clear on: int $flags = ENT_COMPAT | ENT_HTML401

The documentation says "The default is ENT_COMPAT | ENT_HTML401", but goes on two describe them as two different constants.

How can a default be one or the other? In the documentation, there are ten possible values here, so surely only one should be default?

[WingedPanther]

It's a binary or, so the effect is to set BOTH flags to on.

[TenLeftFingers]

Oh, thanks WP. I havenT come across that before. We had OR and Exclusive OR in digital electronics but I couldnt see how it applied here. I assume I can can chain as many as I want that way.

[WingedPanther]

Basically. In general, each flag will have an integer value that's a power of 2 (1, 2, 4, 8, 16, etc). Each corresponds to one bit being set to 1, and the others to 0. When you do a binary or, you end up with several bits set to 1, and you can use binary and (&) to test which are set.

[TenLeftFingers]

That makes total sense, thanks for the explanation WingedPanther.