Skip to content

Commit 6b28d58

Browse files
GirgiasGirgias
committed
PHP 8.4: Start documenting Pdo\Sqlite class
1 parent eb1788b commit 6b28d58

File tree

9 files changed

+853
-507
lines changed

9 files changed

+853
-507
lines changed

‎reference/pdo_sqlite/PDO/sqliteCreateAggregate.xml‎

Lines changed: 8 additions & 249 deletions
Original file line numberDiff line numberDiff line change
@@ -4,265 +4,24 @@
44
<refnamediv>
55
<refname>PDO::sqliteCreateAggregate</refname>
66
<refpurpose>
7-
Registers an aggregating User Defined Function for use in SQL statements
7+
&Alias; <methodname>Pdo\Sqlite::createAggregate</methodname>
88
</refpurpose>
99
</refnamediv>
1010

1111
<refsect1 role="description">
1212
&reftitle.description;
1313
<methodsynopsis>
1414
<modifier>public</modifier> <type>bool</type><methodname>PDO::sqliteCreateAggregate</methodname>
15-
<methodparam><type>string</type><parameter>function_name</parameter></methodparam>
16-
<methodparam><type>callable</type><parameter>step_func</parameter></methodparam>
17-
<methodparam><type>callable</type><parameter>finalize_func</parameter></methodparam>
18-
<methodparam choice="opt"><type>int</type><parameter>num_args</parameter></methodparam>
15+
<methodparam><type>string</type><parameter>name</parameter></methodparam>
16+
<methodparam><type>callable</type><parameter>step</parameter></methodparam>
17+
<methodparam><type>callable</type><parameter>finalize</parameter></methodparam>
18+
<methodparam choice="opt"><type>int</type><parameter>numArgs</parameter><initializer>-1</initializer></methodparam>
1919
</methodsynopsis>
20-
&warn.experimental.func;
21-
<para>
22-
This method is similar to <xref linkend="pdo.sqlitecreatefunction"
23-
/> except that it registers functions that can be used to calculate a
24-
result aggregated across all the rows of a query.
25-
</para>
26-
<para>
27-
The key difference between this method and <xref
28-
linkend="pdo.sqlitecreatefunction" /> is that two functions are
29-
required to manage the aggregate.
30-
</para>
20+
<simpara>
21+
&info.method.alias; <methodname>Pdo\Sqlite::createAggregate</methodname>.
22+
</simpara>
3123
</refsect1>
32-
33-
<refsect1 role="parameters">
34-
&reftitle.parameters;
35-
<para>
36-
<variablelist>
37-
<varlistentry>
38-
<term><parameter>function_name</parameter></term>
39-
<listitem>
40-
<para>
41-
The name of the function used in SQL statements.
42-
</para>
43-
</listitem>
44-
</varlistentry>
45-
<varlistentry>
46-
<term><parameter>step_func</parameter></term>
47-
<listitem>
48-
<para>
49-
Callback function called for each row of the result set. Your PHP
50-
function should accumulate the result and store it in the aggregation
51-
context.
52-
</para>
53-
<para>
54-
This function need to be defined as:
55-
<methodsynopsis>
56-
<type>mixed</type><methodname><replaceable>step</replaceable></methodname>
57-
<methodparam><type>mixed</type><parameter>context</parameter></methodparam>
58-
<methodparam><type>int</type><parameter>rownumber</parameter></methodparam>
59-
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
60-
<methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
61-
</methodsynopsis>
62-
<variablelist>
63-
<varlistentry>
64-
<term><parameter>context</parameter></term>
65-
<listitem>
66-
<para>
67-
&null; for the first row; on subsequent rows it will have the value
68-
that was previously returned from the step function; you should use
69-
this to maintain the aggregate state.
70-
</para>
71-
</listitem>
72-
</varlistentry>
73-
<varlistentry>
74-
<term><parameter>rownumber</parameter></term>
75-
<listitem>
76-
<para>
77-
The current row number.
78-
</para>
79-
</listitem>
80-
</varlistentry>
81-
<varlistentry>
82-
<term><parameter>value</parameter></term>
83-
<listitem>
84-
<para>
85-
The first argument passed to the aggregate.
86-
</para>
87-
</listitem>
88-
</varlistentry>
89-
<varlistentry>
90-
<term><parameter>values</parameter></term>
91-
<listitem>
92-
<para>
93-
Further arguments passed to the aggregate.
94-
</para>
95-
</listitem>
96-
</varlistentry>
97-
</variablelist>
98-
The return value of this function will be used as the
99-
<parameter>context</parameter> argument in the next call of the step or
100-
finalize functions.
101-
</para>
102-
</listitem>
103-
</varlistentry>
104-
<varlistentry>
105-
<term><parameter>finalize_func</parameter></term>
106-
<listitem>
107-
<para>
108-
Callback function to aggregate the "stepped" data from each row.
109-
Once all the rows have been processed, this function will be called
110-
and it should then take the data from the aggregation context and
111-
return the result. This callback function should return a type understood
112-
by SQLite (i.e. <link
113-
linkend="language.types.intro">scalar type</link>).
114-
</para>
115-
<para>
116-
This function need to be defined as:
117-
<methodsynopsis>
118-
<type>mixed</type><methodname><replaceable>fini</replaceable></methodname>
119-
<methodparam><type>mixed</type><parameter>context</parameter></methodparam>
120-
<methodparam><type>int</type><parameter>rowcount</parameter></methodparam>
121-
</methodsynopsis>
122-
<variablelist>
123-
<varlistentry>
124-
<term><parameter>context</parameter></term>
125-
<listitem>
126-
<para>
127-
Holds the return value from the very last call to the step function.
128-
</para>
129-
</listitem>
130-
</varlistentry>
131-
<varlistentry>
132-
<term><parameter>rowcount</parameter></term>
133-
<listitem>
134-
<para>
135-
Holds the number of rows over which the aggregate was performed.
136-
</para>
137-
</listitem>
138-
</varlistentry>
139-
</variablelist>
140-
The return value of this function will be used as the return value for
141-
the aggregate.
142-
</para>
143-
</listitem>
144-
</varlistentry>
145-
<varlistentry>
146-
<term><parameter>num_args</parameter></term>
147-
<listitem>
148-
<para>
149-
Hint to the SQLite parser if the callback function accepts a
150-
predetermined number of arguments.
151-
</para>
152-
</listitem>
153-
</varlistentry>
154-
</variablelist>
155-
</para>
156-
</refsect1>
157-
158-
<refsect1 role="returnvalues">
159-
&reftitle.returnvalues;
160-
<para>
161-
&return.success;
162-
</para>
163-
</refsect1>
164-
165-
<refsect1 role="examples">
166-
&reftitle.examples;
167-
<para>
168-
<example>
169-
<title>max_length aggregation function example</title>
170-
<programlisting role="php">
171-
<![CDATA[
172-
<?php
173-
$data = array(
174-
'one',
175-
'two',
176-
'three',
177-
'four',
178-
'five',
179-
'six',
180-
'seven',
181-
'eight',
182-
'nine',
183-
'ten',
184-
);
185-
$db = new PDO('sqlite::memory:');
186-
$db->exec("CREATE TABLE strings(a)");
187-
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
188-
foreach ($data as $str) {
189-
$insert->execute(array($str));
190-
}
191-
$insert = null;
192-
193-
function max_len_step($context, $rownumber, $string)
194-
{
195-
if (strlen($string) > $context) {
196-
$context = strlen($string);
197-
}
198-
return $context;
199-
}
200-
201-
function max_len_finalize($context, $rowcount)
202-
{
203-
return $context === null ? 0 : $context;
204-
}
205-
206-
$db->sqliteCreateAggregate('max_len', 'max_len_step', 'max_len_finalize');
207-
208-
var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());
209-
210-
?>
211-
]]>
212-
</programlisting>
213-
</example>
214-
</para>
215-
<para>
216-
In this example, we are creating an aggregating function that will
217-
calculate the length of the longest string in one of the columns of the
218-
table. For each row, the <literal>max_len_step</literal> function is
219-
called and passed a <literal>$context</literal> parameter. The context
220-
parameter is just like any other PHP variable and be set to hold an array
221-
or even an object value. In this example, we are simply using it to hold
222-
the maximum length we have seen so far; if the
223-
<literal>$string</literal> has a length longer than the current
224-
maximum, we update the context to hold this new maximum length.
225-
</para>
226-
<para>
227-
After all of the rows have been processed, SQLite calls the
228-
<literal>max_len_finalize</literal> function to determine the aggregate
229-
result. Here, we could perform some kind of calculation based on the
230-
data found in the <literal>$context</literal>. In our simple example
231-
though, we have been calculating the result as the query progressed, so we
232-
simply need to return the context value.
233-
</para>
234-
<tip>
235-
<para>
236-
It is NOT recommended for you to store a copy of the values in the context
237-
and then process them at the end, as you would cause SQLite to use a lot of
238-
memory to process the query - just think of how much memory you would need
239-
if a million rows were stored in memory, each containing a string 32 bytes
240-
in length.
241-
</para>
242-
</tip>
243-
<tip>
244-
<para>
245-
You can use <xref linkend="pdo.sqlitecreatefunction" /> and
246-
<xref linkend="pdo.sqlitecreateaggregate" /> to override SQLite
247-
native SQL functions.
248-
</para>
249-
</tip>
250-
</refsect1>
251-
252-
253-
<refsect1 role="seealso">
254-
&reftitle.seealso;
255-
<para>
256-
<simplelist>
257-
<member><xref linkend="pdo.sqlitecreatefunction" /></member>
258-
<member><function>sqlite_create_function</function></member>
259-
<member><function>sqlite_create_aggregate</function></member>
260-
</simplelist>
261-
</para>
262-
</refsect1>
263-
26424
</refentry>
265-
26625
<!-- Keep this comment at the end of the file
26726
Local variables:
26827
mode: sgml

‎reference/pdo_sqlite/PDO/sqliteCreateCollation.xml‎

Lines changed: 4 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
<refnamediv>
55
<refname>PDO::sqliteCreateCollation</refname>
66
<refpurpose>
7-
Registers a User Defined Function for use as a collating function in SQL statements
7+
&Alias; <methodname>Pdo\Sqlite::createCollation</methodname>
88
</refpurpose>
99
</refnamediv>
1010

@@ -15,90 +15,11 @@
1515
<methodparam><type>string</type><parameter>name</parameter></methodparam>
1616
<methodparam><type>callable</type><parameter>callback</parameter></methodparam>
1717
</methodsynopsis>
18-
&warn.experimental.func;
19-
</refsect1>
20-
21-
<refsect1 role="parameters">
22-
&reftitle.parameters;
23-
<para>
24-
<variablelist>
25-
<varlistentry>
26-
<term><parameter>name</parameter></term>
27-
<listitem>
28-
<para>
29-
Name of the SQL collating function to be created or redefined.
30-
</para>
31-
</listitem>
32-
</varlistentry>
33-
<varlistentry>
34-
<term><parameter>callback</parameter></term>
35-
<listitem>
36-
<para>
37-
The name of a PHP function or user-defined function to apply as a callback, defining the behavior of the collation. It should accept two strings and return as strcmp() does, i.e. it should return -1, 1, or 0 if the first string sorts before, sorts after, or is equal to the second.
38-
</para>
39-
<para>
40-
This function need to be defined as:
41-
<methodsynopsis>
42-
<type>int</type><methodname><replaceable>collation</replaceable></methodname>
43-
<methodparam><type>string</type><parameter>string1</parameter></methodparam>
44-
<methodparam><type>string</type><parameter>string2</parameter></methodparam>
45-
</methodsynopsis>
46-
</para>
47-
</listitem>
48-
</varlistentry>
49-
</variablelist>
50-
</para>
51-
</refsect1>
52-
53-
<refsect1 role="returnvalues">
54-
&reftitle.returnvalues;
55-
<para>
56-
&return.success;
57-
</para>
58-
</refsect1>
59-
60-
<refsect1 role="examples">
61-
&reftitle.examples;
62-
<para>
63-
<example>
64-
<title><function>PDO::sqliteCreateCollation</function> example</title>
65-
<programlisting role="php">
66-
<![CDATA[
67-
<?php
68-
$db = new PDO('sqlite::memory:');
69-
$db->exec("CREATE TABLE test (col1 string)");
70-
$db->exec("INSERT INTO test VALUES ('a1')");
71-
$db->exec("INSERT INTO test VALUES ('a10')");
72-
$db->exec("INSERT INTO test VALUES ('a2')");
73-
74-
$db->sqliteCreateCollation('NATURAL_CMP', 'strnatcmp');
75-
foreach ($db->query("SELECT col1 FROM test ORDER BY col1") as $row) {
76-
echo $row['col1'] . "\n";
77-
}
78-
echo "\n";
79-
foreach ($db->query("SELECT col1 FROM test ORDER BY col1 COLLATE NATURAL_CMP") as $row) {
80-
echo $row['col1'] . "\n";
81-
}
82-
?>
83-
]]>
84-
</programlisting>
85-
&example.outputs;
86-
<screen>
87-
<![CDATA[
88-
a1
89-
a10
90-
a2
91-
92-
a1
93-
a2
94-
a10
95-
]]>
96-
</screen>
97-
</example>
98-
</para>
18+
<simpara>
19+
&info.method.alias; <methodname>Pdo\Sqlite::createCollation</methodname>.
20+
</simpara>
9921
</refsect1>
10022
</refentry>
101-
10223
<!-- Keep this comment at the end of the file
10324
Local variables:
10425
mode: sgml

0 commit comments

Comments
 (0)