Edit report at https://bugs.php.net/bug.php?id=77348&edit=1
ID: 77348
Comment by: chealer at gmail dot com
Reported by: chealer at gmail dot com
Summary: Misleading Edit button (Experimental but not flagged
as such)
Status: Open
Type: Bug
Package: Online Doc Editor problem
PHP Version: Irrelevant
Block user comment: N
Private report: N
New Comment:
After I submitted a proposal for prepare(), the Patches for review tab indicated "(0)".
Yet, it contained stuff from more than 20 people.
The contents of my proposal follow:
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 337261 $ -->
<refentry xml:id="pdo.prepare" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>PDO::prepare</refname>
<refpurpose>
Prepares a statement for execution and returns a statement object
</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier>
<type>PDOStatement</type><methodname>PDO::prepare</methodname>
<methodparam><type>string</type><parameter>statement</parameter></methodparam>
<methodparam
choice="opt"><type>array</type><parameter>driver_options</parameter><initializer>array()</initializer></methodparam>
</methodsynopsis>
<para>
Prepares an SQL statement template to be executed by the
<function>PDOStatement::execute</function> method. The statement template can
contain zero or more named (:name) or question mark (?) parameter markers
for which real values will be substituted when the statement template is executed.
Both named and question mark parameter markers cannot be used within the same
SQL statement template; only one or the other parameter style.
Use these parameters to bind any user-input, do not include the user-input
directly in the query.
</para>
<para>
You must include a unique parameter marker for each value you wish to pass
in to the statement when you call <function>PDOStatement::execute</function>.
You cannot use a named parameter marker of the same name more than once in a prepared
statement, unless emulation mode is on.
</para>
<note>
<para>
Parameter markers can represent a complete data literal only.
Neither part of literal, nor keyword, nor identifier, nor whatever arbitrary query
part can be bound using parameters. For example, you cannot bind multiple values
to a single parameter in the IN() clause of an SQL statement.
</para>
</note>
<para>
Calling <function>PDO::prepare</function> and
<function>PDOStatement::execute</function> for statements that will be
issued multiple times with different parameter values optimizes the
performance of your application by allowing the driver to negotiate
client and/or server-side caching of the query plan and meta information. Also, calling
<function>PDO::prepare</function> and
<function>PDOStatement::execute</function> helps to prevent SQL injection attacks by
eliminating the need to
manually quote and escape the parameters.
</para>
<para>
PDO will emulate prepared statements/bound parameters for drivers that do
not natively support them, and can also rewrite named or question mark
style parameter markers to something more appropriate, if the driver
supports one style but not the other.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>statement</parameter></term>
<listitem>
<para>
This must be a valid SQL statement template for the target database server.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>driver_options</parameter></term>
<listitem>
<para>
This array holds one or more key=>value pairs to set
attribute values for the PDOStatement object that this method
returns. You would most commonly use this to set the
<literal>PDO::ATTR_CURSOR</literal> value to
<literal>PDO::CURSOR_SCROLL</literal> to request a scrollable cursor.
Some drivers have driver-specific options that may be set at
prepare-time.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
If the database server successfully prepares the statement,
<function>PDO::prepare</function> returns a
<classname>PDOStatement</classname> object.
If the database server cannot successfully prepare the statement,
<function>PDO::prepare</function> returns &false; or emits
<classname>PDOException</classname> (depending on <link
linkend="pdo.error-handling">error handling</link>).
</para>
<note>
<para>
Emulated prepared statements does not communicate with the database server
so <function>PDO::prepare</function> does not check the statement.
</para>
</note>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example><title>Prepare an SQL statement template with named parameters</title>
<programlisting role="php">
<![CDATA[
<?php
/* Execute a prepared statement by passing an array of values */
$sql = 'SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour';
$sth = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY));
$sth->execute(array(':calories' => 150, ':colour' => 'red'));
$red = $sth->fetchAll();
$sth->execute(array(':calories' => 175, ':colour' =>
'yellow'));
$yellow = $sth->fetchAll();
?>
]]>
</programlisting>
</example>
<example>
<title>Prepare an SQL statement template with question mark parameters</title>
<programlisting role="php">
<![CDATA[
<?php
/* Execute a prepared statement by passing an array of values */
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->execute(array(150, 'red'));
$red = $sth->fetchAll();
$sth->execute(array(175, 'yellow'));
$yellow = $sth->fetchAll();
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>PDO::exec</function></member>
<member><function>PDO::query</function></member>
<member><function>PDOStatement::execute</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Previous Comments:
------------------------------------------------------------------------
[2018-12-26 18:29:16] chealer at gmail dot com
Description:
------------
I noticed tens of issues in PHP documentation over the years. Sometimes, I tried to get them fixed.
I opened bug reports, and about 5 times I must have tried to use "Php Docbook Online
Editor".
Unfortunately, to my knowledge none of my attempts to fix the doc with Php Docbook Online Editor
worked. I had such a strong suspicion that the last 2 attempts, I noted what I did to confirm.
As reported in http://news.php.net/php.doc/969385815 I submitted a
proposal in 2015 for addslashes which was not accepted. It appears that this proposal is completely
lost. I cannot even find any evidence that it was made. I reported this to the phpdoc mailing list
years ago and did not get any answer:
http://news.php.net/php.doc/969385815
Some time later, as I did not trust Php Docbook Online Editor, I submitted issue report #70120: https://bugs.php.net/bug.php?id=70120&edit=2
Unfortunately, the page still has several issues, so I tried to use Php Docbook Online Editor once
again to actually solve the issue on 2016-03-26, but that time I took notes. And unfortunately, over
2 years later, my proposal is neither accepted, nor even acknowledged in any way that I can see. I
did not receive any email, which is not surprising given that I was not asked for an address.
So once again, the Edit button which seems to suggest the documentation is a wiki misled me. I
thought I could edit easily, but in fact I put my time in the garbage.
I am guessing that Php Docbook Online Editor is not completely broken, so I am not going to suggest
dismantlement, but at least one of the following should be done:
1. Make it less likely that contributors reach Php Docbook Online Editor from the documentation.
Either remove the link, move it somewhere less prominent, or change the label ("Propose a
change / Edit" would already be less misleading).
2. Implement basic features and do minimal quality assurance to confirm that these features work.
3. Add a warning when launching Php Docbook Online Editor that it is experimental, or - better yet -
list the main areas known to be broken.
------------------------------------------------------------------------
--
Edit this bug report at https://bugs.php.net/bug.php?id=77348&edit=1