• 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Documentation improvements

#4
(11-09-2014, 05:45 PM)RobertSF Wrote: Codeigniter is known for its good documentation, but that doesn't mean it can't be improved. I'd like to suggest a Documentation subforum under Issues, where we can point out errors and suggest improvements. I think this is important, especially considering that many people starting with Codeigniter are also new to PHP.

Here is a concrete example. The documentation states under the section Callbacks: Your own Validation Functions,



Quote:To invoke a callback just put the function name in a rule, with "callback_" as the rule prefix. If you need to receive an extra parameter in your callback function, just add it normally after the function name between square brackets, as in: "callback_foo[bar]", then it will be passed as the second argument of your callback function.

The above is not incorrect but it can lead novice programmers to tear their hair out. The problem is that the example shows how to pass the string 'bar' to the callback function, yet the more common case would be passing the value in a variable. And to pass the value of variable $bar, the example should read "callback_foo[$bar]" while reminding the reader that double-quotes must be used if PHP is to parse $bar as a variable. The documentation could further clarify,



Quote:To pass the value of a variable, you must use concatenation, double quotes, or complex syntax. Like this:
concatenation: 'callback_foo['. $bar . ']'
double quotes: "callback_foo[$bar]"
complex syntax: "callback_foo[{$bar['snafu']}]"
That last style is especially helpful when passing array elements.

The documentation could also link to the PHP manual, specifically to:
Strings - Variable Parsing, and Why is $foo[bar] wrong?.

You can quibble with the example I'm giving, but I still think we can make a community effort to improve the manual. What do you think?

It's the CodeIgniter user guide, not the PHP manual. It's not supposed to teach you what the difference between single and double quotes is.

(11-11-2014, 11:54 AM)RobertSF Wrote: In the section explaining $this->input->post(), it would be helpful if the documentation noted that array elements cannot be retrieved individually.

This comes up when you use an array in your forms. If you use $book['isbn'], $book['author'], $book['title'], $book['price'] in your form, for example, upon posting the form, the $_POST array will contain an array called book with keys isbn, author, title, and price. You can retrieve those one by one directly by accessing the $_POST variable, like this:


PHP Code:
$price $_POST['book']['price']; 

But using the Post method of the Input class, you must get the whole array and then access the individual elements, like this:


PHP Code:
$book $this->input->post('book');
$price $book['price']; 

This is one of the new features in CI 3.0:


PHP Code:
$price $this->input->post('book[price]'); 
Reply


Messages In This Thread
Documentation improvements - by RobertSF - 11-09-2014, 05:45 PM
RE: Documentation improvements - by RobertSF - 11-11-2014, 11:54 AM
RE: Documentation improvements - by Chroma - 11-14-2014, 09:30 AM
RE: Documentation improvements - by Narf - 11-17-2014, 04:41 AM
RE: Documentation improvements - by RobertSF - 11-17-2014, 03:21 PM
RE: Documentation improvements - by Narf - 11-18-2014, 02:36 AM
RE: Documentation improvements - by includebeer - 11-17-2014, 07:01 PM
RE: Documentation improvements - by RobertSF - 11-17-2014, 07:03 PM
RE: Documentation improvements - by includebeer - 11-17-2014, 08:28 PM
RE: Documentation improvements - by twpmarketing - 11-18-2014, 03:13 PM
RE: Documentation improvements - by slax0r - 11-18-2014, 01:11 AM
RE: Documentation improvements - by sv3tli0 - 11-18-2014, 03:20 AM
RE: Documentation improvements - by jlp - 12-31-2014, 04:28 PM
RE: Documentation improvements - by RobertSF - 12-31-2014, 05:25 PM

Digg   Delicious   Reddit   Facebook   Twitter   StumbleUpon  


  Theme © 2014 iAndrew  
Powered By MyBB, © 2002-2020 MyBB Group.