Edit report at https://bugs.php.net/bug.php?id=77348&edit=1
ID: 77348
Updated by: cmb@php.net
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:
Back to the issue at hand: the relevant line that would have to be
changed or removed is
<https://github.com/php/web-php/blob/bda2d837724d59efe8580b9232d6d60fa545cf5b/include/shared-manual.inc#L448>
Previous Comments:
------------------------------------------------------------------------
[2018-12-27 11:32:57] cmb@php.net
> The last proposal I made was in 2016, [â¦]
Ah, I see. Basically, I think the patch is fine, but I would use
âtemplateâ only when referring to the $statement parameter. See
the attached patch pdo-prepare.
> The question is where it shows.
I'm afraid, nowhere.
> [â¦] but there is something wrong in the system as a whole (the
> engine plus its operators) [â¦]
ACK. However, I don't think we should spend much time on
improving PhDOE, given that there are way more suitable
alternatives *almost* readily available, such as Github pull
requests. Personally, I even prefer to have a bug report with an
attached patch instead of a submission to PhDOE, unless it's about
a simple typo fix or such. While this is slightly more work, it
allows to discuss the patches and to track the progress.
------------------------------------------------------------------------
[2018-12-27 11:32:49] cmb@php.net
The following patch has been added/updated:
Patch Name: pdo-prepare
Revision: 1545910369
URL: https://bugs.php.net/patch-display.php?bug=77348&patch=pdo-prepare&revision=1545910369
------------------------------------------------------------------------
[2018-12-27 04:06:08] chealer at gmail dot com
Thank you for checking cmb. The last proposal I made was in 2016, so it is expected that it
doesn't show in the Patches for review tab. The question is where it shows.
I am not saying that reviewers are mishandling proposals, but there is something wrong in the system
as a whole (the engine plus its operators) if the end result is that people who logged in and did
not refuse to provide any contact information end up not being notified of rejections. And really
wrong if even by returning to the website they can't figure out who rejected, when or why.
------------------------------------------------------------------------
[2018-12-26 23:38:29] cmb@php.net
I suppose these patches have not been swallowed by PhDOE, but
rather have been rejected, maybe because they have gone stale
(PdDOE apparently doesn't store diffs, but rather the complete
file, so if someone else edits the file, the presented patch often
makes no sense anymore). Also, we likely delete unsuitable
patches without any notice to submitters, since often it is not
possible to notify them.
> 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).
I think that we should remove the link altogether. A considerable
percentage of submitted patches are done by trolls who try to make
malicious or at least obviously bad changes. It's rather annoying
to check and delete these patches (if the latter is even allowed).
In the (hopefully not too) long run we should really switch to
Git[1] to be able to replace PhDOE with Github pull requests.
> After I submitted a proposal for prepare(), the Patches for
> review tab indicated "(0)". Yet, it contained stuff from more than
> 20 people.
Indeed, the count appears to be broken. However, I can't find
your patch regarding PDO::prepare, and there are currently only
submitted patches from eight people for the *English* language.
[1] <http://news.php.net/php.doc/969386622>
------------------------------------------------------------------------
[2018-12-26 18:39:19] chealer at gmail dot com
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
-->
------------------------------------------------------------------------
The remainder of the comments for this report are too long. To view
the rest of the comments, please view the bug report online at
https://bugs.php.net/bug.php?id=77348
--
Edit this bug report at https://bugs.php.net/bug.php?id=77348&edit=1