TehnoBlog

Article Updated: 15 Jan 2021

Article Update: PHP.net documentation site was changed in some areas since we originally published this article back in 2015. Some things are improved, but, unfortunately, other confusing stuff was also added – completely unnecessary in our honest opinion!

If you are new to PHP language and coding world in general, over 99% chances are that you will most probably first end up on a PHP.net official manual website via internet search. And you will definitely get confused with strange “examples” and constructs at that place. Why is PHP.net manual so complicated and hard to understand? Well, it is not complicated at all if you know PHP language well, but the writing style may be confusing to newbies / beginners.

PHP Logo

And, as it is almost always the case, you will seek your help somewhere else with an easy-to-read examples and not too many confusing stuff in the coding sentence. However, sooner you learn to READ and UNDERSTAND php.net website, the better and beneficial it will be for your learning skills and advancement.

Welcome to PHP.net manual for newbies: How to use and understand PHP.net manual website examples

Let’s start with a simple example: built-in function str_replace() in this brief article: at first, you might get overwhelmed with the long and stuffed string which supposedly represents how you should use the function. However, once you learn how to properly “read” the structure of, it will make much more sense to you.

New 2020/2021 documentation

Since PHP.net website’s update, some things are no longer confusing as they were before. Here’s an updated screenshot of the below described str_replace() function:

PHP.net Manual Explained for Newbies
(updated documentation)

VARIABLE TYPE (formerly MIXED)

In order to avoid potential confusion and improve manual’s readability, mixed was replaced by a combination of string|array or array|string markings, to clearly indicate which types are supported or expected in the respectable placeholders.

Note: mixed is not completely gone – it is still used for functions which accept a wide range of variable types and it would be too cumbersome to list all of them

OPTIONAL VALUES / EXTRA PARAMETERS (formerly inside square brackets [ ])

New PHP.net documentation no longer uses square brackets [ ] to enclose optional parameter(s). This is a good move in our opinion, because it was a major source of confusion in the old days.

OUTPUT RESULT TYPE (NEW! section)

This part of the manual overhaul is not something we really like, to be honest. In the new version, at the end of the function a new colon (:) symbol is introduced along the type(s) of the output result. This is not really necessary, because below each function there is a paragraph section named Result which explains what to expect (e.g. a string or an array, object etc.). It’s a bit confusing, but font is in green color, at least, to minimize potential confusion.

Remember: Everything after last : symbol is NOT a code or part of the actual function!

Once we clear descriptions and optional part we get str_replace() in familiar simplest form

Old 2015 documentation

WARNING: The following section of the article refers to an older PHP.net manual website, which was updated in the meantime. While you will certainly learn few important things from it that complement above updated version, be aware of the fact that it does not reflect the current manual with the new markings and conventions

PHP.net Manual Explained for Newbies
(old documentation from 2015)

MIXED

this is NOT part of the code itself at all, it is literally a simple word descriptor which only purpose is to help you understand what type of variables (string, array, boolean, integer, object, resource etc.) can be placed in the variable next to it (left-to-right or LTR reading is assumed here).

SQUARE BRACKETS [ ]

Square Brackets are probably the most confusing part of the PHP.net manual for new users. This is because of the lack of understanding what square brackets represents / mean. Simply put, in our example above anything between [ and ] is OPTIONAL CODE. This means that it is not necessary to include anything that is written inside the square brackets for str_replace function to work.

However, sometimes you will need those extra parameters to improve your own code, and then you will use them. But, you SHOULD NOT write the actual square brackets in this (and many other similar examples) at all! Otherwise, your PHP debugger will throw you an error.

In case you decide to use an optional parameter(s), don’t forget to separate them with the comma, the same way you separate the mandatory variables. Otherwise, comma is simply left out, and this is the reason it is placed inside the [ ] brackets section.

HIDDEN DEFAULT VALUES

Many times square brackets described in PHP.net manual will contain not only optional parameters (variables or values), but also DEFAULT values. This is not part of the manual itself, but rather PHP’s way to define value in case the programmer did not specify it.

PHP.net Manual Explained for Newbies 2
(click to enlarge)

For example, in our second example with a built-in function define() we can see another optional BOOLEAN parameter $case_insensitive. If you do not specifically define it (simply said, you left it out / not use it), PHP will in that case assume that you set it to false value. Just be carefull with this, it may give you some headache because you did not pay attention.

CONCLUSION

This is it so far, hope you find these beginner’s tips useful. Happy coding!